From 5e389c9ceb91dfd4528d85204676fa43e078077d Mon Sep 17 00:00:00 2001 From: David Abram Date: Mon, 9 Nov 2026 16:47:37 +0100 Subject: [PATCH] style: Simplify comments and agent guidance Remove redundant implementation comments across the CLI, specifications, configuration sources, packaging scripts, and vendored Pkl modules. Reduce AGENTS.md to the repository's current comment and Rust conventions while preserving executable behavior. Co-authored-by: SCE --- .../skills/quint-modeling/examples/ewd426.qnt | 49 --- .../examples/tendermint/choreo.qnt | 22 -- .../tendermint/spells/basicSpells.qnt | 126 ------- .../examples/tendermint/tendermint.qnt | 143 +------- .../examples/tendermint/tendermintTest.qnt | 31 -- .../skills/quint-modeling/examples/ewd426.qnt | 49 --- .../examples/tendermint/choreo.qnt | 22 -- .../tendermint/spells/basicSpells.qnt | 126 ------- .../examples/tendermint/tendermint.qnt | 143 +------- .../examples/tendermint/tendermintTest.qnt | 31 -- .opencode/plugins/sce-agent-trace.ts | 7 - .opencode/plugins/sce-bash-policy.ts | 6 - .pi/extensions/sce/index.ts | 32 -- AGENTS.md | 265 +------------- cli/assets/hooks/commit-msg | 7 +- cli/assets/hooks/post-commit | 7 +- cli/assets/hooks/pre-commit | 7 +- cli/build.rs | 16 - .../001_repository_schema.sql | 10 - .../002_repository_source_instance_id.sql | 8 - .../004_mutation_trace_protocol.sql | 20 -- cli/src/cli_schema.rs | 4 - cli/src/services/agent_trace.rs | 14 - .../services/agent_trace/repository_path.rs | 3 - cli/src/services/agent_trace_db/lifecycle.rs | 3 - cli/src/services/agent_trace_db/mod.rs | 32 -- cli/src/services/agent_trace_db/repository.rs | 60 ---- cli/src/services/agent_trace_export/mod.rs | 17 - cli/src/services/agent_trace_storage/mod.rs | 29 -- cli/src/services/agent_trace_sync/mod.rs | 31 -- cli/src/services/auth.rs | 8 - cli/src/services/auth_db/mod.rs | 4 - cli/src/services/bash_policy.rs | 12 - cli/src/services/codex_hook_config.rs | 44 --- cli/src/services/codex_hook_policy.rs | 105 ------ cli/src/services/codex_hook_trust.rs | 115 ------ cli/src/services/command_registry.rs | 10 - cli/src/services/config/policy.rs | 8 - cli/src/services/config/resolver.rs | 9 - cli/src/services/config/schema.rs | 10 - cli/src/services/config/types.rs | 10 - cli/src/services/db/encryption_key.rs | 8 - cli/src/services/db/mod.rs | 114 ------ cli/src/services/default_paths.rs | 19 - cli/src/services/doctor/inspect.rs | 72 ---- cli/src/services/doctor/render.rs | 6 - cli/src/services/doctor/types.rs | 22 -- cli/src/services/error.rs | 7 - .../fixtures/mcp_probe/block.sh | 4 - .../fixtures/mcp_probe/dump.sh | 11 - .../fixtures/mcp_probe/run-probes.sh | 11 - .../hooks/commit_hooks/attribution_tests.rs | 7 - cli/src/services/lifecycle.rs | 3 - cli/src/services/local_db/mod.rs | 4 - cli/src/services/mutation_trace/lineage.rs | 36 -- .../services/mutation_trace/lineage/tests.rs | 16 - cli/src/services/mutation_trace/mbt/driver.rs | 25 -- cli/src/services/mutation_trace/mbt/mod.rs | 10 - cli/src/services/mutation_trace/mbt/model.rs | 53 --- cli/src/services/mutation_trace/mbt/tests.rs | 46 --- cli/src/services/mutation_trace/mod.rs | 145 -------- cli/src/services/mutation_trace/protocol.rs | 180 ---------- .../mutation_trace/runtime/coordinator.rs | 26 -- .../mutation_trace/runtime/external_taint.rs | 49 --- .../mutation_trace/runtime/git_snapshot.rs | 8 - .../runtime/mutation_attribution.rs | 24 -- .../runtime/mutation_attribution/tests.rs | 1 - cli/src/services/mutation_trace/store.rs | 148 -------- cli/src/services/mutation_trace/tests.rs | 52 --- cli/src/services/mutation_trace/types.rs | 98 ----- cli/src/services/patch.rs | 115 +----- cli/src/services/repository_identity/mod.rs | 37 -- .../services/repository_identity/resolve.rs | 36 +- cli/src/services/resilience.rs | 4 - cli/src/services/security.rs | 1 - cli/src/services/structured_patch.rs | 12 - cli/src/services/style.rs | 28 -- cli/src/services/sync/auto_sync.rs | 6 - cli/src/services/sync/mod.rs | 2 - cli/src/services/sync/progress.rs | 8 - cli/src/services/sync/render_sync.rs | 2 - cli/src/services/sync/sync.rs | 25 -- .../opencode-sce-agent-trace-plugin.ts | 7 - .../bash-policy-runtime.test.ts | 8 - .../opencode-bash-policy-plugin.ts | 6 - config/lib/pi-plugin/sce-pi-extension.ts | 32 -- config/lib/sce-info/tests/sce-splash.test.ts | 5 - config/pkl/base/decision-skill.pkl | 4 - .../pkl/base/optional-workflow-manifest.pkl | 5 - config/pkl/base/workflow-brownfield.pkl | 16 - config/pkl/base/workflow-catalog.pkl | 6 - config/pkl/base/workflow-change-to-plan.pkl | 12 - config/pkl/base/workflow-commit.pkl | 12 - config/pkl/base/workflow-content.pkl | 74 ---- config/pkl/base/workflow-context-sync.pkl | 4 - config/pkl/base/workflow-handover.pkl | 9 - config/pkl/base/workflow-next-task.pkl | 12 - config/pkl/base/workflow-validate.pkl | 22 -- .../pkl/deps/org.json_schema/JsonSchema.pkl | 339 +----------------- config/pkl/deps/pkl.experimental.uri/URI.pkl | 118 +----- config/pkl/renderers/claude-content.pkl | 4 - config/pkl/renderers/codex-content.pkl | 17 - config/pkl/renderers/codex-metadata.pkl | 28 -- .../renderers/generation-contract-check.pkl | 46 --- .../pkl/renderers/metadata-coverage-check.pkl | 9 - config/pkl/renderers/opencode-content.pkl | 9 - config/pkl/renderers/pi-content.pkl | 7 - config/pkl/renderers/workflow-composite.pkl | 32 -- flake.nix | 76 ---- nix/flatpak/manifest.nix | 3 - nix/tests/npm-nixos-vm.nix | 7 - npm/test/release-fixture.sh | 28 -- packaging/flatpak/sce-flatpak.sh | 2 - spec/mutation_cursor.qnt | 48 --- 114 files changed, 32 insertions(+), 4111 deletions(-) diff --git a/.agents/skills/quint-modeling/examples/ewd426.qnt b/.agents/skills/quint-modeling/examples/ewd426.qnt index 4ee7fb571..8dd873768 100644 --- a/.agents/skills/quint-modeling/examples/ewd426.qnt +++ b/.agents/skills/quint-modeling/examples/ewd426.qnt @@ -1,59 +1,20 @@ -/** - * ewd426's Stabilizing Token Ring (EWD426) - * K state machine - * This implementation ensures that from some time on, - * exactly one token circulates in a set of nodes, - * - * Mahtab Norouzi, Josef Widder, Informal Systems, 2024-2025 - */ - -/* ============================================================================= - * quint-modeling REFERENCE EXAMPLE — communication model: SHARED MEMORY - * ----------------------------------------------------------------------------- - * Why this is bundled: it is the canonical *shared-memory* shape — there is NO - * message medium. Processes coordinate by reading common state: each node's - * `state_transition` reads its left/right neighbours in `var system: int -> State`. - * Contrast with the Choreo example (tendermint/), which is message-passing. - * - * Demonstrates, against the quint-modeling guidelines: - * - Grouped-map state `var system: int -> State` (one entry per node). - * - Guarded action `step` picks a node that *can* move; no no-op fallback. - * - Logic in pure defs `has_token`, `state_transition`, `count_tokens`. - * - const-instantiation the parametric `self_stabilization` module is run via - * the concrete `ewd426` instance (N = 5, K = 7). This is - * the pattern the skill's spine teaches: a `const` cannot - * run until instantiated. Run with `--main=ewd426`. - * - temporal LIVENESS `convergence` / `closure` / `persistence` — the system - * self-stabilizes to exactly one token. (The only bundled - * example with temporal properties.) - * - * The `broken_ewd426` instance (N = 3, K = 2) is a deliberately-broken config kept for - * contrast — useful to show what a property *failing* looks like. - * - * Verified clean on Quint 0.32.0. See ../examples/README.md for re-verification commands. - * ============================================================================= */ module self_stabilization { - // Number of nodes in the ring const N: int const K: int - /// Ensures the state space is larger than the number of nodes assume _ = K >= N val bottom = 0 val top = N - /// Mapping of node indices to their states var system: int -> int - /// Check if a node has the token pure def has_token(nodes: int -> int, index: int): bool = if (index == bottom) nodes.get(bottom) == nodes.get(top) else not(nodes.get(index) == nodes.get(index - 1)) - /// Update the state of a specific node pure def state_transition(nodes: int -> int, index: int): int = if (not(has_token(nodes, index))) nodes.get(index) @@ -62,40 +23,31 @@ module self_stabilization { else nodes.get(index - 1) - /// Initialize all nodes with non-deterministic states action init = all { nondet initial = 0.to(N).setOfMaps(0.to(K - 1)).oneOf() system' = initial } - /// Pick a single active node non-deterministically and update its state action step = { nondet node = 0.to(N).filter(i => has_token(system, i)).oneOf() system' = system.set(node, state_transition(system, node)) } - /// Pick several active nodes non-deterministically and update their state. - /// Closer to the distributed demon is discussed in EWD 391. We are not - /// considering interleaving in the execution of state_transition here action distributed_step = { nondet nodes = 0.to(N).filter(i => has_token(system, i)).powerset().exclude(Set()).oneOf() system' = nodes.fold(system, (s, x) => s.set(x, state_transition(system, x))) } - // Pure function to count how many tokens exist pure def count_tokens(nodes: int -> int): int = { 0.to(N).filter(i => has_token(nodes, i)).size() } - // Temporal properties temporal convergence = step.weakFair(Set(system)) implies eventually(count_tokens(system) == 1) temporal closure = always(count_tokens(system) == 1 implies always(count_tokens(system) == 1)) temporal persistence = step.weakFair(Set(system)) implies eventually(always(count_tokens(system) == 1)) - // Invariant def tokenInv = count_tokens(system) > 0 - /// to better see the token in the repl pure def show_token(nodes: int -> int): int -> bool = nodes.keys().mapBy(i => has_token(nodes, i)) } @@ -105,6 +57,5 @@ module ewd426 { } module broken_ewd426 { - // This should break the assumption of K >= N. See #1182. import self_stabilization(N = 3, K = 2).* } diff --git a/.agents/skills/quint-modeling/examples/tendermint/choreo.qnt b/.agents/skills/quint-modeling/examples/tendermint/choreo.qnt index 4845ffbb3..4d252410e 100644 --- a/.agents/skills/quint-modeling/examples/tendermint/choreo.qnt +++ b/.agents/skills/quint-modeling/examples/tendermint/choreo.qnt @@ -1,16 +1,6 @@ -/** - * Choreo: Choreograph distributed protocols in Quint - * - * Read the documentation: TODO LINK - * - * Gabriela Moreira, Josef Widder and Yassine Boukhari, - * Informal Systems, 2025 - */ - module choreo { import basicSpells.* from "spells/basicSpells" - // TODO: try moving process id to local context type LocalState[process_id, ext] = { process_id: process_id | ext @@ -35,17 +25,14 @@ module choreo { extensions: ext } - // This is the message routing to the # handler type Listener[p, s, m, e, ce, ext] = (LocalContext[p, s, m, e, ext]) => Set[Transition[p, s, m, e, ce]] type DeterministicListener[p, s, m, e, ce, ext] = (LocalContext[p, s, m, e, ext]) => Transition[p, s, m, e, ce] - // Only needed for micro_step type Input[m, e] = Message(m) | Event(e) - // Only needed for micro_step type MicroListener[p, s, m, e, ce, ext] = (LocalContext[p, s, m, e, ext], Input[m, e]) => Set[Transition[p, s, m, e, ce]] @@ -59,13 +46,6 @@ module choreo { | TriggerEvent(e) | CustomEffect(ce) - /// A displayer is a function that takes a global context and returns a displayable representation of it. - /// This is used to visualize the state of the system for debugging or monitoring purposes. - /// After type instantiation, it should have the following signature: - /// ``` - /// (Environment) => Display - /// ``` - /// The display type can be anything. type Displayer[p, s, m, e, ext, d] = (GlobalContext[p, s, m, e, ext]) => d pure def apply_effect( @@ -122,7 +102,6 @@ module choreo { transitions: Set[Transition[p, s, m, e, ce]], apply_custom_effect: EffectProcessor[p, s, m, e, ce, extensions], ): bool = - // FIXME: Quint was supposed to detect determinism alone if (transitions.size() == 1) { val transition = transitions.getOnlyElement() val post_env = apply_effect(s, v, transition, apply_custom_effect) @@ -139,7 +118,6 @@ module choreo { apply_custom_effect: EffectProcessor[p, s, m, e, ce, extensions], displayer: Displayer[p, s, m, e, extensions, d], ): bool = - // FIXME: Quint was supposed to detect determinism alone if (transitions.size() == 1) { val transition = transitions.getOnlyElement() val post_env = apply_effect(s, v, transition, apply_custom_effect) diff --git a/.agents/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt b/.agents/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt index 6c75bcbe7..a6ae97706 100644 --- a/.agents/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt +++ b/.agents/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt @@ -1,14 +1,6 @@ -/** - * This module collects definitions that are ubiquitous. - * One day they will become the standard library of Quint. - */ module basicSpells { - /// Option type, which may hold some value or none type Option[a] = Some(a) | None - /// An annotation for writing preconditions. - /// - @param cond condition to check - /// - @returns true if and only if cond evaluates to true pure def require(cond: bool): bool = cond run requireTest = all { @@ -16,12 +8,6 @@ module basicSpells { assert(not(require(false))), } - /// A convenience operator that returns a string error code, - /// if the condition does not hold true. - /// - /// - @param cond condition to check - /// - @param error a non-empty error message - /// - @returns "", when cond holds true; otherwise error pure def requires(cond: bool, error: str): str = { if (cond) "" else error } @@ -32,11 +18,6 @@ module basicSpells { } - /// Compute the maximum of two integers. - /// - /// - @param i first integer - /// - @param j second integer - /// - @returns the maximum of i and j pure def max(i: int, j: int): int = { if (i > j) i else j } @@ -49,11 +30,6 @@ module basicSpells { assert(max(-5, -3) == -3), } - /// Compute the minimum of two integers. - /// - /// - @param i first integer - /// - @param j second integer - /// - @returns the minimum of i and j pure def min(i: int, j: int): int = { if (i < j) i else j } @@ -66,10 +42,6 @@ module basicSpells { assert(min(-5, -3) == -5), } - /// Compute the absolute value of an integer - /// - /// - @param i : an integer whose absolute value we are interested in - /// - @returns |i|, the absolute value of i pure def abs(i: int): int = { if (i < 0) -i else i } @@ -80,11 +52,6 @@ module basicSpells { assert(abs(0) == 0), } - /// Remove a set element. - /// - /// - @param s a set to remove an element from - /// - @param elem an element to remove - /// - @returns a new set that contains all elements of set but elem pure def setRemove(s: Set[a], elem: a): Set[a] = { s.exclude(Set(elem)) } @@ -94,11 +61,6 @@ module basicSpells { assert(Set() == Set().setRemove(3)), } - /// Adds an element to a set. - /// - /// - @param s a set to add an element to - /// - @param elem an element to add - /// - @returns a new set that contains all elements of set and elem pure def setAdd(s: Set[a], elem: a): Set[a] = { s.union(Set(elem)) } @@ -109,11 +71,6 @@ module basicSpells { assert(Set(2,4) == Set(2,4).setAdd(4)), } - /// Test whether a key is present in a map - /// - /// - @param m a map to query - /// - @param key the key to look for - /// - @returns true if and only map has an entry associated with key pure def has(m: a -> b, key: a): bool = { m.keys().contains(key) } @@ -123,13 +80,6 @@ module basicSpells { assert(not(Map(2 -> 3, 4 -> 5).has(6))), } - /// Get the map value associated with a key, or the default, - /// if the key is not present. - /// - /// - @param m the map to query - /// - @param key the key to search for - /// - @returns the value associated with the key, if key is - /// present in the map, and default otherwise pure def getOrElse(m: a -> b, key: a, default: b): b = { if (m.has(key)) { m.get(key) @@ -143,12 +93,6 @@ module basicSpells { assert(Map(2 -> 3, 4 -> 5).getOrElse(7, 11) == 11), } - /// Remove a map entry. - /// - /// - @param m a map to remove an entry from - /// - @param key the key of an entry to remove - /// - @returns a new map that contains all entries of map - /// that do not have the key key pure def mapRemove(m: a -> b, key: a): a -> b = { m.keys().setRemove(key).mapBy(k => m.get(k)) } @@ -158,12 +102,6 @@ module basicSpells { assert(Map() == Map().mapRemove(3)), } - /// Removes a set of map entries. - /// - /// - @param m a map to remove entries from - /// - @param ks a set of keys for entries to remove from the map - /// - @returns a new map that contains all entries of map - /// that do not have a key in keys pure def mapRemoveAll(m: a -> b, ks: Set[a]): a -> b = { m.keys().exclude(ks).mapBy(k => m.get(k)) } @@ -175,10 +113,6 @@ module basicSpells { assert(m.mapRemoveAll(Set(5, 99999)) == Map(3 -> 4, 7 -> 8)), } - /// Get the set of values of a map. - /// - /// - @param map a map from type a to type b - /// - @returns the set of all values in the map pure def values(m: a -> b): Set[b] = { m.keys().map(k => m.get(k)) } @@ -189,10 +123,6 @@ module basicSpells { assert(values(Map(1 -> 2, 2 -> 3, 3 -> 2)) == Set(2, 3)), } - /// Whether a set is empty - /// - /// - @param s a set of any type - /// - @returns true iff the set is the empty set pure def empty(s: Set[a]): bool = s == Set() run emptyTest = all { @@ -201,11 +131,6 @@ module basicSpells { assert(empty(Set(Set())) == false), } - /// Sort a list, given the ordering operator. - /// - /// - @param list a list to sort - /// - @param lt a definition of "less than" - /// - @returns the sorted version of list pure def sortList(list: List[a], lt: (a, a) => bool): List[a] = { pure def insertInOrder(sortedList: List[a], num: a): List[a] = { match range(0, sortedList.length()).findFirst(i => not(lt(sortedList[i], num))) { @@ -222,11 +147,6 @@ module basicSpells { assert([ 1, 1, 3, 5, 5 ] == sortList([ 5, 1, 3, 1, 5 ], (x, y) => x < y)), } - /// Apply an operator to all values of a map - /// - /// - @param m: a map of any type - /// - @param f: an operator with one argument with the same type as the map's values - /// - @returns a map with same keys as m and f applied to the values pure def transformValues(m: a -> b, f: (b) => c): a -> c = { m.keys().mapBy(k => f(m.get(k))) } @@ -236,11 +156,6 @@ module basicSpells { assert(m.transformValues(x => x + 1) == Map("a" -> 2, "b" -> 3)) } - /// map a function over a list - /// - /// - @param l: a list of any type - /// - @param f: a function to apply to each element of the list - /// - @returns a list of the results of applying f to each element of l pure def listMap(l: List[a], f: (a) => b): List[b] = { range(0, l.length()).foldl([], (acc, i) => { acc.append(f(l[i])) @@ -252,10 +167,6 @@ module basicSpells { assert(listMap([1, 2, 3], x => x > 1) == [false, true, true]), } - /// The last element of a list - /// - /// - @param v: a list of any type - /// - @returns the last element of the list pure def last(v: List[a]): a = { v[v.length() - 1] } @@ -265,12 +176,6 @@ module basicSpells { assert(last([1]) == 1), } - /// `decreasingRange(i, j)` is the list of integers between `j` and `i` - /// both `i` and `j` are inclusive. - /// The behavior is undefined if `i < j`. - /// - /// - @param start: the first integer in the range - /// - @param end: the last integer in the range pure def decreasingRange(start: int, end: int): List[int] = { range(end, start + 1).foldl([], (acc, i) => { List(i).concat(acc) @@ -281,12 +186,6 @@ module basicSpells { assert(decreasingRange(5, 1) == [5, 4, 3, 2, 1]), } - /// `takeWhile(l, cond)` is the longest prefix of `l` such that all elements - /// satisfy the condition `cond`. - /// - /// - @param l: a list of any type - /// - @param cond: a function that takes an element of the list and returns a boolean - /// - @returns the longest prefix of `l` such that all elements satisfy `cond` pure def takeWhile(l: List[a], cond: (a) => bool): List[a] = { pure val result = l.foldl(([], true), (acc, e) => { if (acc._2 and cond(e)) { @@ -303,11 +202,6 @@ module basicSpells { assert(takeWhile([1, 5, 4, 3], (x) => x % 2 == 1) == [1, 5]), } - /// `isPrefixOf(l1, l2)` is true iff `l1` is a prefix of `l2`. - /// - /// - @param l1: a list of any type - /// - @param l2: a list of same type as `l1` - /// - @returns true iff `l1` is a prefix of `l2` pure def isPrefixOf(l1: List[a], l2: List[a]): bool = { if (l1.length() > l2.length()) { false @@ -324,12 +218,6 @@ module basicSpells { assert(isPrefixOf([], [])), } - /// `find(s, f)` is an element of `s` that satisfies the predicate `f`, or None - /// if no such element exists. - /// - /// - @param s: a set of any type - /// - @param f: a function that takes an element of the set and returns a boolean - /// - @returns an element of `s` that satisfies `f`, or None pure def find(s, f) = s.fold(None, (a, i) => if (f(i)) Some(i) else a) run findTest = all { @@ -337,12 +225,6 @@ module basicSpells { assert(find(Set(1, 2, 3), x => x == 4) == None), } - /// `findFirst(l, f)` is the first element of `l` that satisfies the predicate `f`, or None - /// if no such element exists. - /// - /// - @param l: a list of any type - /// - @param f: a function that takes an element of the list and returns a boolean - /// - @returns the first element of `l` that satisfies `f`, or None pure def findFirst(l, f) = l.foldl(None, (a, i) => if (a == None and f(i)) Some(i) else a) run findFirstTest = all { @@ -350,14 +232,6 @@ module basicSpells { assert(findFirst([1, 2, 3], x => x == 4) == None), } - /// `setByWithDefault(m, k, op, default)` is a map that is the same as `m` except that - /// the value associated with `k` is `op(m[k])` if `k` is present in `m`, and `op(default)` otherwise. - /// - /// - @param m: a map from type `a` to type `b` - /// - @param k: a key of type `a` - /// - @param op: a function to transform the value of the key - /// - @param default: the value to use if the key is not present in the map - /// - @returns a new map with the updated key. pure def setByWithDefault(m: a -> b, k: a, op: (b) => b, default: b): a -> b = { if (m.has(k)) m.setBy(k, op) diff --git a/.agents/skills/quint-modeling/examples/tendermint/tendermint.qnt b/.agents/skills/quint-modeling/examples/tendermint/tendermint.qnt index 26dfde0f6..9eba87093 100644 --- a/.agents/skills/quint-modeling/examples/tendermint/tendermint.qnt +++ b/.agents/skills/quint-modeling/examples/tendermint/tendermint.qnt @@ -1,42 +1,3 @@ -/* ============================================================================= - * quint-modeling REFERENCE EXAMPLE — communication model: MESSAGE-PASSING (Choreo) - * ----------------------------------------------------------------------------- - * Why this is bundled: it is the canonical *Choreo framework* spec — a real BFT - * consensus engine (Tendermint), and the source of the examples in - * ../../../quint-lang/guidelines/choreo.md. Choreo is a different programming model - * from plain Quint (its own `choreo::` API), so it cannot be inferred — you have to - * see one. Contrast with the shared-memory example (../ewd426.qnt). - * - * READ THIS when modelling ANY distributed protocol where parties exchange messages — - * consensus/BFT, replication, atomic commit, leader election, reliable broadcast/gossip, - * request/response, a mempool. It is the default reference for message-passing systems - * (not just consensus); the patterns below transfer. Use ../ewd426.qnt instead only when - * parts coordinate through SHARED STATE rather than messages. - * - * Demonstrates the `choreo::cue` PATTERN — separate *when* from *what*: - * - `listen_*(ctx): Set[Params]` — the messages/conditions that match (Set[()] for - * state/quorum-only triggers). - * - `broadcast_*` / `act_*(ctx, p): Transition` — the reaction for each match. - * - `main_listener` wires them with `choreo::cue(ctx, listen, act)` (x7) — reads - * like the protocol at a glance. - * Plus: real `agreement` / `validity` / `accountability` invariants. - * - * QUICK READ (to learn the pattern without reading all ~760 lines — anchored to - * names so it survives upstream re-sync): read `listen_proposal_in_propose` + - * `broadcast_prevote_for_proposal` (one cue pair), then `main_listener` (the wiring), - * then the `agreement` / `validity` / `accountability` invariants. The rest is full - * protocol depth. - * - * TESTS: in the sibling `tendermintTest.qnt` (this spec has no `run`s, per the - * test-separation guideline — quint-lang/guidelines/tests.md). That file also holds - * the concrete instances; the spec here is parametric (const F/CORRECT/FAULTY/...), - * so it cannot run on its own — run an instance: - * quint run tendermintTest.qnt --main=valid --invariant="agreement and validity and accountability" - * The `no_agreement` instance there is a deliberate agreement-violation demo. - * - * Dependencies (bundled alongside): ./choreo.qnt, ./spells/basicSpells.qnt. - * Verified clean on Quint 0.32.0. See ../README.md for re-verification commands. - * ============================================================================= */ module tendermint { import basicSpells.* from "./spells/basicSpells" import choreo(processes = NODES) as choreo from "./choreo" @@ -54,9 +15,6 @@ module tendermint { type TimeoutKind = ProposeTimeout | PreVoteTimeout | PreCommitTimeout type TimeoutEvent = { kind: TimeoutKind, round: Round } - /// The ID of a value. In the implementation, this would be a hash of the value. - /// Here, we wrap it in a record and don't convert it back into a value. - /// This keeps the property that v1.id() == v2.id() iff v1 == v2. type ValueId = { hashed: Value } type Node = str @@ -94,7 +52,6 @@ module tendermint { type Event = TimeoutEvent type Extensions = Bookkeeping - /* Boilerplate */ type LocalState = choreo::LocalState[Node, StateFields] type LocalContext = choreo::LocalContext[Node, StateFields, Message, Event, Extensions] type Transition = choreo::Transition[Node, StateFields, Message, Event, CustomEffects] @@ -105,7 +62,6 @@ module tendermint { Event, Extensions ] - /* End of boilerplate */ pure def get_proposals(messages: Set[Message]): Set[ProposeMsg] = messages.filterMap(m => { @@ -180,13 +136,11 @@ module tendermint { s.stage == ProposeStage } - // Message guards: predicates on the messages that can use the state as context def message_guard = (p) => and { p.valid_round == -1, p.src == PROPOSER.get(s.round), } - // Apply Guards val proposals = messages.get_proposals() proposals.filter(p => and { message_guard(p), @@ -197,14 +151,12 @@ module tendermint { pure def broadcast_prevote_for_proposal(ctx: LocalContext, p: ProposeMsg): Transition = { val s = ctx.state - // Broadcast the PreVote message for the proposal pure val effects = if (valid(p.proposal) and (s.locked_round == -1 or s.locked_value == Some(p.proposal))) { Set(choreo::Broadcast(PreVote({ src: s.process_id, round: s.round, id: Some(id(p.proposal)) }))) } else { Set(choreo::Broadcast(PreVote({ src: s.process_id, round: s.round, id: None }))) } - // TODO -> add timeout and logging effects { post_state: { ...s, stage: PreVoteStage }, effects: effects.setAdd(choreo::CustomEffect(CollectEvidence(Propose(p)))) @@ -232,7 +184,7 @@ module tendermint { val pre_votes = messages.get_pre_votes() proposals.filter(p => and { - pre_votes.filter(q => q.id == Some(p.proposal.id()) and q.round == p.valid_round).size() >= 2 * F + 1 // quorum size is F + 1 + pre_votes.filter(q => q.id == Some(p.proposal.id()) and q.round == p.valid_round).size() >= 2 * F + 1 }) } @@ -240,14 +192,12 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for prevotes that contributed to this decision val contributing_prevotes = messages.get_pre_votes().filter(pv => pv.round == p.valid_round and pv.id == Some(id(p.proposal)) ) val prevote_evidence = contributing_prevotes.map(pv => choreo::CustomEffect(CollectEvidence(PreVote(pv)))) val evidence = Set(choreo::CustomEffect(CollectEvidence(Propose(p)))).union(prevote_evidence) - // Broadcast the PreVote message for the proposal val effects = if (valid(p.proposal) and (s.locked_round <= p.valid_round or s.locked_value == Some(p.proposal))) { Set(choreo::Broadcast(PreVote({ src: s.process_id, round: s.round, id: Some(id(p.proposal))}))) } else { @@ -265,11 +215,10 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Do we have a quorum of PreVotes in the current round def message_guard = (pv) => (pv.round == s.round) val quorum = messages.get_pre_votes().filter(pv => and { message_guard(pv), - }).size() >= 2 * F + 1 // quorum size is F + 1 + }).size() >= 2 * F + 1 if (quorum) { Set(()) @@ -281,7 +230,6 @@ module tendermint { pure def trigger_prevote_timeout(ctx: LocalContext, _params: ()): Transition = { val s = ctx.state - // If we have a quorum, we can move to precommit stage { post_state: s, effects: Set(choreo::TriggerEvent({ kind: PreVoteTimeout, round: s.round })) @@ -296,7 +244,6 @@ module tendermint { s.stage == PreVoteStage, } - // Do we have a quorum of PreVotes in the current round def message_guard = (pv) => (pv.round == s.round and pv.id == None) val prevotes = messages.get_pre_votes().filter(pv => message_guard(pv)) val quorum = prevotes.map(m => m.src).size() >= 2 * F + 1 @@ -312,13 +259,11 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for all nil prevotes that enabled this decision val nil_prevotes = messages.get_pre_votes().filter(pv => pv.round == s.round and pv.id == None ) val prevote_evidence = nil_prevotes.map(pv => choreo::CustomEffect(CollectEvidence(PreVote(pv)))) - // If we have a quorum, we can move to precommit stage { post_state: { ...s, stage: PreCommitStage }, effects: Set( @@ -331,11 +276,10 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Do we have a quorum of PreCommits in the current round def message_guard = (pc) => (pc.round == s.round) val quorum = messages.get_pre_commits().filter(pc => and { message_guard(pc), - }).map(m => m.src).size() >= 2 * F + 1 // quorum size is F + 1 + }).map(m => m.src).size() >= 2 * F + 1 if (quorum) { Set(()) @@ -347,7 +291,6 @@ module tendermint { pure def trigger_precommit_timeout(ctx: LocalContext, _params: ()): Transition = { val s = ctx.state - // If we have a quorum, we can move to decided stage { post_state: s, effects: Set(choreo::TriggerEvent({ kind: PreCommitTimeout, round: s.round })) @@ -373,7 +316,6 @@ module tendermint { proposals.filter(p => and { message_guard(p), state_guard, - // Check for quorum of prevotes for this proposal in current round pre_votes.filter(pv => and { pv.round == s.round, pv.id == Some(id(p.proposal)) @@ -385,16 +327,13 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for prevotes that enabled this decision val enabling_prevotes = messages.get_pre_votes().filter(pv => pv.round == s.round and pv.id == Some(id(p.proposal)) ) val prevote_evidence = enabling_prevotes.map(pv => choreo::CustomEffect(CollectEvidence(PreVote(pv)))) if (s.stage == PreVoteStage) { - // If in prevote stage, broadcast precommit and move to precommit stage { - // Move to precommit stage and update values post_state: { ...s, stage: PreCommitStage, @@ -409,7 +348,6 @@ module tendermint { ).union(prevote_evidence) } } else { - // Just update valid value if already in precommit { post_state: { ...s, @@ -431,7 +369,7 @@ module tendermint { def message_guard = (p) => and { p.src == PROPOSER.get(p.round), - p.round <= s.round // Can decide on current or past rounds + p.round <= s.round } val proposals = messages.get_proposals() @@ -440,7 +378,6 @@ module tendermint { proposals.filter(p => and { message_guard(p), state_guard, - // Check for quorum of precommits for this proposal pre_commits.filter(pc => and { pc.round == p.round, pc.id == Some(id(p.proposal)) @@ -452,13 +389,11 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for precommits that enabled this decision val enabling_precommits = messages.get_pre_commits().filter(pc => pc.round == p.round and pc.id == Some(id(p.proposal)) ) val precommit_evidence = enabling_precommits.map(pc => choreo::CustomEffect(CollectEvidence(PreCommit(pc)))) - // Make decision and move to decided stage { post_state: { ...s, @@ -564,7 +499,6 @@ module tendermint { } } - // Card(powset) = 4096 val byzantine_messages_1 = { val rounds = Set(0) val byzantine_proposals = rounds.map(r => { @@ -585,21 +519,15 @@ module tendermint { }) }).flatten() - // Reintegrate byzantine proposals Set(byzantine_prevotes, byzantine_precommits, byzantine_proposals).flatten() } - // TODO (Gabriela): I don't understand this val byzantine_messages = { - // We can have at most 2^F faulty nodes, so we take the powerset of the byzantine messages - // to simulate all possible combinations of byzantine messages. - // 10 dummy prevotes for future rounds val dummy_prevotes = 1000.to(1025).map(r => { PreVote({ src: "p4", round: r, id: None }) }) dummy_prevotes - //Set() } action init = choreo::init({ @@ -628,50 +556,6 @@ module tendermint { ) - // -------------------------------- semantic symmetry utilities -------------------------------- - // TODO: Update these functions to work with choreo library - /* - type StateFingerprint = { - round: Round, - stage: Stage, - decision: Option[Value], - locked_value: Option[Value], - locked_round: Round, - valid_value: Option[Value], - valid_round: Round, - after_prevote_for_first_time: bool, - precommit_quorum: bool, - is_proposer: bool, - } - - pure def select_representatives(s: GlobalState): Set[Node] = { - val states = s.system.values() - val unique = group_by_fingerprint(states) - unique.setByAll((k, group) => group.filter(n =>(n.in(CORRECT))).takeOne()). - values().filter(n => n != None).map(n => n.unwrap()) - } - - def group_by_fingerprint(s: Set[LocalState]): StateFingerprint -> Set[Node] = { - val init = Map() - s.fold(init, (acc, state) => { - val key = { - round: state.round, - stage: state.stage, - decision: state.decision, - locked_value: state.locked_value, - locked_round: state.locked_round, - valid_value: state.valid_value, - valid_round: state.valid_round, - after_prevote_for_first_time: state.after_prevote_for_first_time, - precommit_quorum: state.precommit_quorum, - is_proposer: state.process_id == PROPOSER.get(state.round) - } - acc.setByWithDefault(key, (e) => e.setAdd(state.process_id),Set()) - }) - } - */ - // -------------------------------- semantic symmetry utilities -------------------------------- - val correct_nodes = s.system.values().filter(s => s.process_id.in(CORRECT)) val agreement = tuples(correct_nodes, correct_nodes).forall(((p1, p2)) => { p1.decision == None or p2.decision == None or p1.decision == p2.decision @@ -683,8 +567,6 @@ module tendermint { val all_decided = not(correct_nodes.exists(v => v.decision == None)) - // Witness for a to find a case where a node is in the decided stage while another is prevote - // state val stages = and { s.system.values().map(v => v.stage).contains(ProposeStage), @@ -693,15 +575,12 @@ module tendermint { s.system.values().map(v => v.stage).contains(DecidedStage) } - // Evidence-based properties - pure def equivocation_in(n: Node, evidence: Set[{ src: Node, round: Round | other }]): bool = { tuples(evidence, evidence).exists(((e1, e2)) => { e1 != e2 and e1.src == n and e2.src == n and e1.round == e2.round }) } - /// Equivocation by a node n def equivocation_by(n: Node): bool = { or { n.equivocation_in(s.extensions.evidence_propose), @@ -710,7 +589,6 @@ module tendermint { } } - /// Amnesic behavior by a node n def amnesia_by(n: Node): bool = { tuples(ROUNDS, ROUNDS).exists(((r1, r2)) => { r1 < r2 and tuples(VALID_VALUES, VALID_VALUES).exists(((v1, v2)) => { @@ -732,12 +610,8 @@ module tendermint { }) } - /// Validity: the decided block satisfies the predefined predicate valid(). val validity = correct_nodes.forall(s => s.decision.in(VALID_VALUES.map(v => Some(v)).setAdd(None))) - /// The protocol safety. Two cases are possible: - /// 1. There is no fork, that is, Agreement holds true. - /// 2. A subset of faulty processes demonstrates equivocation or amnesia. val accountability = or { agreement, FAULTY.powerset().exists(f => and { @@ -747,24 +621,15 @@ module tendermint { } const F: int - /// The set of correct processes const CORRECT: Set[Node] - /// The set of faulty processes const FAULTY: Set[Node] - /// Which node is the proposer in each round const PROPOSER: Round -> Node - /// Which value is proposed in each round. - /// Values from rounds with correct nodes (in PROPOSER) are considered valid values. const VALUES: Round -> Value const MAX_ROUND: Round - /// The set of all nodes pure val NODES = CORRECT.union(FAULTY) - /// The set of all rounds (prepared by the constants) pure val ROUNDS = VALUES.keys() - /// The set of all correct values (prepared by the constants) - //pure val VALID_VALUES = ROUNDS.filter(k => PROPOSER.get(k).in(CORRECT)).map(k => VALUES.get(k)) pure val VALID_VALUES = Set("v0", "v1", "v2") action step_with(v: Node, listener: LocalContext => Set[Transition]): bool = diff --git a/.agents/skills/quint-modeling/examples/tendermint/tendermintTest.qnt b/.agents/skills/quint-modeling/examples/tendermint/tendermintTest.qnt index 8d0cc8a2d..0d05372a0 100644 --- a/.agents/skills/quint-modeling/examples/tendermint/tendermintTest.qnt +++ b/.agents/skills/quint-modeling/examples/tendermint/tendermintTest.qnt @@ -1,24 +1,4 @@ -/* ============================================================================= - * Tests for the Tendermint Choreo reference example. - * - * Per the test-separation guideline (quint-lang/guidelines/tests.md), `run` tests - * live in this file, NOT in the spec — `tendermint.qnt` has no `run` definitions. - * Each module here instantiates the parametric `tendermint` spec with concrete - * consts (the const-instantiation pattern) and drives a scenario: - * - `valid` — a run where consensus succeeds; `line28Test` exercises the - * proposal/prevote/precommit cue chain across a round change. - * - `no_agreement` — a faulty proposer equivocates; `disagreementTest` shows the - * `agreement` invariant being violated (a counterexample demo). - * - * Run / test (from this directory): - * quint run tendermintTest.qnt --main=valid --invariant="agreement and validity and accountability" - * quint test tendermintTest.qnt --main=valid - * quint run tendermintTest.qnt --main=no_agreement --invariant=accountability - * quint test tendermintTest.qnt --main=no_agreement - * ============================================================================= */ module valid { - // quint run tendermintTest.qnt --main valid --invariant="agreement and validity and accountability" - // quint test tendermintTest.qnt --main valid import basicSpells.* from "./spells/basicSpells" @@ -44,10 +24,8 @@ module valid { .then("p2".with_cue(listen_quorum_precommits_any, ()).perform(trigger_precommit_timeout)) .then(step_with("p2", on_precommit_timeout)) - // p2 starts a new round .expect(s.system.get("p2").round == 1) - // since p2 is the proposer in the new round, it will propose the stored valid value .expect(and { s.system.get("p2").stage == ProposeStage, s.messages.values().forall(ms => { @@ -55,8 +33,6 @@ module valid { }) }) - // Which enables line 28 to be called by p2, as it is in propose stage and can receive - // the new proposal with valid_round 0. .then("p2" .with_cue(listen_proposal_in_propose_prevote, { proposal: "v0", round: 1, src: "p2", valid_round: 0 }) .perform(broadcast_prevote_with_validation) @@ -65,18 +41,11 @@ module valid { } module no_agreement { - // Should fail: - // quint run tendermintTest.qnt --main no_agreement --invariants=agreement validity accountability - // - // Should succeed (accountability should still hold): - // quint run tendermintTest.qnt --main no_agreement --invariant=accountability - // quint test tendermintTest.qnt --main no_agreement import tendermint( F = 1, CORRECT = Set("p1", "p2"), FAULTY = Set("p3","p4"), - // a faulty node is the proposer in the first round PROPOSER = Map(0 -> "p3", 1 -> "p2", 2 -> "p3", 3 -> "p4"), VALUES = Map(0 -> "v0", 1 -> "v1", 2 -> "v2", 3 -> "v3"), MAX_ROUND = 4 diff --git a/.claude/skills/quint-modeling/examples/ewd426.qnt b/.claude/skills/quint-modeling/examples/ewd426.qnt index 4ee7fb571..8dd873768 100644 --- a/.claude/skills/quint-modeling/examples/ewd426.qnt +++ b/.claude/skills/quint-modeling/examples/ewd426.qnt @@ -1,59 +1,20 @@ -/** - * ewd426's Stabilizing Token Ring (EWD426) - * K state machine - * This implementation ensures that from some time on, - * exactly one token circulates in a set of nodes, - * - * Mahtab Norouzi, Josef Widder, Informal Systems, 2024-2025 - */ - -/* ============================================================================= - * quint-modeling REFERENCE EXAMPLE — communication model: SHARED MEMORY - * ----------------------------------------------------------------------------- - * Why this is bundled: it is the canonical *shared-memory* shape — there is NO - * message medium. Processes coordinate by reading common state: each node's - * `state_transition` reads its left/right neighbours in `var system: int -> State`. - * Contrast with the Choreo example (tendermint/), which is message-passing. - * - * Demonstrates, against the quint-modeling guidelines: - * - Grouped-map state `var system: int -> State` (one entry per node). - * - Guarded action `step` picks a node that *can* move; no no-op fallback. - * - Logic in pure defs `has_token`, `state_transition`, `count_tokens`. - * - const-instantiation the parametric `self_stabilization` module is run via - * the concrete `ewd426` instance (N = 5, K = 7). This is - * the pattern the skill's spine teaches: a `const` cannot - * run until instantiated. Run with `--main=ewd426`. - * - temporal LIVENESS `convergence` / `closure` / `persistence` — the system - * self-stabilizes to exactly one token. (The only bundled - * example with temporal properties.) - * - * The `broken_ewd426` instance (N = 3, K = 2) is a deliberately-broken config kept for - * contrast — useful to show what a property *failing* looks like. - * - * Verified clean on Quint 0.32.0. See ../examples/README.md for re-verification commands. - * ============================================================================= */ module self_stabilization { - // Number of nodes in the ring const N: int const K: int - /// Ensures the state space is larger than the number of nodes assume _ = K >= N val bottom = 0 val top = N - /// Mapping of node indices to their states var system: int -> int - /// Check if a node has the token pure def has_token(nodes: int -> int, index: int): bool = if (index == bottom) nodes.get(bottom) == nodes.get(top) else not(nodes.get(index) == nodes.get(index - 1)) - /// Update the state of a specific node pure def state_transition(nodes: int -> int, index: int): int = if (not(has_token(nodes, index))) nodes.get(index) @@ -62,40 +23,31 @@ module self_stabilization { else nodes.get(index - 1) - /// Initialize all nodes with non-deterministic states action init = all { nondet initial = 0.to(N).setOfMaps(0.to(K - 1)).oneOf() system' = initial } - /// Pick a single active node non-deterministically and update its state action step = { nondet node = 0.to(N).filter(i => has_token(system, i)).oneOf() system' = system.set(node, state_transition(system, node)) } - /// Pick several active nodes non-deterministically and update their state. - /// Closer to the distributed demon is discussed in EWD 391. We are not - /// considering interleaving in the execution of state_transition here action distributed_step = { nondet nodes = 0.to(N).filter(i => has_token(system, i)).powerset().exclude(Set()).oneOf() system' = nodes.fold(system, (s, x) => s.set(x, state_transition(system, x))) } - // Pure function to count how many tokens exist pure def count_tokens(nodes: int -> int): int = { 0.to(N).filter(i => has_token(nodes, i)).size() } - // Temporal properties temporal convergence = step.weakFair(Set(system)) implies eventually(count_tokens(system) == 1) temporal closure = always(count_tokens(system) == 1 implies always(count_tokens(system) == 1)) temporal persistence = step.weakFair(Set(system)) implies eventually(always(count_tokens(system) == 1)) - // Invariant def tokenInv = count_tokens(system) > 0 - /// to better see the token in the repl pure def show_token(nodes: int -> int): int -> bool = nodes.keys().mapBy(i => has_token(nodes, i)) } @@ -105,6 +57,5 @@ module ewd426 { } module broken_ewd426 { - // This should break the assumption of K >= N. See #1182. import self_stabilization(N = 3, K = 2).* } diff --git a/.claude/skills/quint-modeling/examples/tendermint/choreo.qnt b/.claude/skills/quint-modeling/examples/tendermint/choreo.qnt index 4845ffbb3..4d252410e 100644 --- a/.claude/skills/quint-modeling/examples/tendermint/choreo.qnt +++ b/.claude/skills/quint-modeling/examples/tendermint/choreo.qnt @@ -1,16 +1,6 @@ -/** - * Choreo: Choreograph distributed protocols in Quint - * - * Read the documentation: TODO LINK - * - * Gabriela Moreira, Josef Widder and Yassine Boukhari, - * Informal Systems, 2025 - */ - module choreo { import basicSpells.* from "spells/basicSpells" - // TODO: try moving process id to local context type LocalState[process_id, ext] = { process_id: process_id | ext @@ -35,17 +25,14 @@ module choreo { extensions: ext } - // This is the message routing to the # handler type Listener[p, s, m, e, ce, ext] = (LocalContext[p, s, m, e, ext]) => Set[Transition[p, s, m, e, ce]] type DeterministicListener[p, s, m, e, ce, ext] = (LocalContext[p, s, m, e, ext]) => Transition[p, s, m, e, ce] - // Only needed for micro_step type Input[m, e] = Message(m) | Event(e) - // Only needed for micro_step type MicroListener[p, s, m, e, ce, ext] = (LocalContext[p, s, m, e, ext], Input[m, e]) => Set[Transition[p, s, m, e, ce]] @@ -59,13 +46,6 @@ module choreo { | TriggerEvent(e) | CustomEffect(ce) - /// A displayer is a function that takes a global context and returns a displayable representation of it. - /// This is used to visualize the state of the system for debugging or monitoring purposes. - /// After type instantiation, it should have the following signature: - /// ``` - /// (Environment) => Display - /// ``` - /// The display type can be anything. type Displayer[p, s, m, e, ext, d] = (GlobalContext[p, s, m, e, ext]) => d pure def apply_effect( @@ -122,7 +102,6 @@ module choreo { transitions: Set[Transition[p, s, m, e, ce]], apply_custom_effect: EffectProcessor[p, s, m, e, ce, extensions], ): bool = - // FIXME: Quint was supposed to detect determinism alone if (transitions.size() == 1) { val transition = transitions.getOnlyElement() val post_env = apply_effect(s, v, transition, apply_custom_effect) @@ -139,7 +118,6 @@ module choreo { apply_custom_effect: EffectProcessor[p, s, m, e, ce, extensions], displayer: Displayer[p, s, m, e, extensions, d], ): bool = - // FIXME: Quint was supposed to detect determinism alone if (transitions.size() == 1) { val transition = transitions.getOnlyElement() val post_env = apply_effect(s, v, transition, apply_custom_effect) diff --git a/.claude/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt b/.claude/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt index 6c75bcbe7..a6ae97706 100644 --- a/.claude/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt +++ b/.claude/skills/quint-modeling/examples/tendermint/spells/basicSpells.qnt @@ -1,14 +1,6 @@ -/** - * This module collects definitions that are ubiquitous. - * One day they will become the standard library of Quint. - */ module basicSpells { - /// Option type, which may hold some value or none type Option[a] = Some(a) | None - /// An annotation for writing preconditions. - /// - @param cond condition to check - /// - @returns true if and only if cond evaluates to true pure def require(cond: bool): bool = cond run requireTest = all { @@ -16,12 +8,6 @@ module basicSpells { assert(not(require(false))), } - /// A convenience operator that returns a string error code, - /// if the condition does not hold true. - /// - /// - @param cond condition to check - /// - @param error a non-empty error message - /// - @returns "", when cond holds true; otherwise error pure def requires(cond: bool, error: str): str = { if (cond) "" else error } @@ -32,11 +18,6 @@ module basicSpells { } - /// Compute the maximum of two integers. - /// - /// - @param i first integer - /// - @param j second integer - /// - @returns the maximum of i and j pure def max(i: int, j: int): int = { if (i > j) i else j } @@ -49,11 +30,6 @@ module basicSpells { assert(max(-5, -3) == -3), } - /// Compute the minimum of two integers. - /// - /// - @param i first integer - /// - @param j second integer - /// - @returns the minimum of i and j pure def min(i: int, j: int): int = { if (i < j) i else j } @@ -66,10 +42,6 @@ module basicSpells { assert(min(-5, -3) == -5), } - /// Compute the absolute value of an integer - /// - /// - @param i : an integer whose absolute value we are interested in - /// - @returns |i|, the absolute value of i pure def abs(i: int): int = { if (i < 0) -i else i } @@ -80,11 +52,6 @@ module basicSpells { assert(abs(0) == 0), } - /// Remove a set element. - /// - /// - @param s a set to remove an element from - /// - @param elem an element to remove - /// - @returns a new set that contains all elements of set but elem pure def setRemove(s: Set[a], elem: a): Set[a] = { s.exclude(Set(elem)) } @@ -94,11 +61,6 @@ module basicSpells { assert(Set() == Set().setRemove(3)), } - /// Adds an element to a set. - /// - /// - @param s a set to add an element to - /// - @param elem an element to add - /// - @returns a new set that contains all elements of set and elem pure def setAdd(s: Set[a], elem: a): Set[a] = { s.union(Set(elem)) } @@ -109,11 +71,6 @@ module basicSpells { assert(Set(2,4) == Set(2,4).setAdd(4)), } - /// Test whether a key is present in a map - /// - /// - @param m a map to query - /// - @param key the key to look for - /// - @returns true if and only map has an entry associated with key pure def has(m: a -> b, key: a): bool = { m.keys().contains(key) } @@ -123,13 +80,6 @@ module basicSpells { assert(not(Map(2 -> 3, 4 -> 5).has(6))), } - /// Get the map value associated with a key, or the default, - /// if the key is not present. - /// - /// - @param m the map to query - /// - @param key the key to search for - /// - @returns the value associated with the key, if key is - /// present in the map, and default otherwise pure def getOrElse(m: a -> b, key: a, default: b): b = { if (m.has(key)) { m.get(key) @@ -143,12 +93,6 @@ module basicSpells { assert(Map(2 -> 3, 4 -> 5).getOrElse(7, 11) == 11), } - /// Remove a map entry. - /// - /// - @param m a map to remove an entry from - /// - @param key the key of an entry to remove - /// - @returns a new map that contains all entries of map - /// that do not have the key key pure def mapRemove(m: a -> b, key: a): a -> b = { m.keys().setRemove(key).mapBy(k => m.get(k)) } @@ -158,12 +102,6 @@ module basicSpells { assert(Map() == Map().mapRemove(3)), } - /// Removes a set of map entries. - /// - /// - @param m a map to remove entries from - /// - @param ks a set of keys for entries to remove from the map - /// - @returns a new map that contains all entries of map - /// that do not have a key in keys pure def mapRemoveAll(m: a -> b, ks: Set[a]): a -> b = { m.keys().exclude(ks).mapBy(k => m.get(k)) } @@ -175,10 +113,6 @@ module basicSpells { assert(m.mapRemoveAll(Set(5, 99999)) == Map(3 -> 4, 7 -> 8)), } - /// Get the set of values of a map. - /// - /// - @param map a map from type a to type b - /// - @returns the set of all values in the map pure def values(m: a -> b): Set[b] = { m.keys().map(k => m.get(k)) } @@ -189,10 +123,6 @@ module basicSpells { assert(values(Map(1 -> 2, 2 -> 3, 3 -> 2)) == Set(2, 3)), } - /// Whether a set is empty - /// - /// - @param s a set of any type - /// - @returns true iff the set is the empty set pure def empty(s: Set[a]): bool = s == Set() run emptyTest = all { @@ -201,11 +131,6 @@ module basicSpells { assert(empty(Set(Set())) == false), } - /// Sort a list, given the ordering operator. - /// - /// - @param list a list to sort - /// - @param lt a definition of "less than" - /// - @returns the sorted version of list pure def sortList(list: List[a], lt: (a, a) => bool): List[a] = { pure def insertInOrder(sortedList: List[a], num: a): List[a] = { match range(0, sortedList.length()).findFirst(i => not(lt(sortedList[i], num))) { @@ -222,11 +147,6 @@ module basicSpells { assert([ 1, 1, 3, 5, 5 ] == sortList([ 5, 1, 3, 1, 5 ], (x, y) => x < y)), } - /// Apply an operator to all values of a map - /// - /// - @param m: a map of any type - /// - @param f: an operator with one argument with the same type as the map's values - /// - @returns a map with same keys as m and f applied to the values pure def transformValues(m: a -> b, f: (b) => c): a -> c = { m.keys().mapBy(k => f(m.get(k))) } @@ -236,11 +156,6 @@ module basicSpells { assert(m.transformValues(x => x + 1) == Map("a" -> 2, "b" -> 3)) } - /// map a function over a list - /// - /// - @param l: a list of any type - /// - @param f: a function to apply to each element of the list - /// - @returns a list of the results of applying f to each element of l pure def listMap(l: List[a], f: (a) => b): List[b] = { range(0, l.length()).foldl([], (acc, i) => { acc.append(f(l[i])) @@ -252,10 +167,6 @@ module basicSpells { assert(listMap([1, 2, 3], x => x > 1) == [false, true, true]), } - /// The last element of a list - /// - /// - @param v: a list of any type - /// - @returns the last element of the list pure def last(v: List[a]): a = { v[v.length() - 1] } @@ -265,12 +176,6 @@ module basicSpells { assert(last([1]) == 1), } - /// `decreasingRange(i, j)` is the list of integers between `j` and `i` - /// both `i` and `j` are inclusive. - /// The behavior is undefined if `i < j`. - /// - /// - @param start: the first integer in the range - /// - @param end: the last integer in the range pure def decreasingRange(start: int, end: int): List[int] = { range(end, start + 1).foldl([], (acc, i) => { List(i).concat(acc) @@ -281,12 +186,6 @@ module basicSpells { assert(decreasingRange(5, 1) == [5, 4, 3, 2, 1]), } - /// `takeWhile(l, cond)` is the longest prefix of `l` such that all elements - /// satisfy the condition `cond`. - /// - /// - @param l: a list of any type - /// - @param cond: a function that takes an element of the list and returns a boolean - /// - @returns the longest prefix of `l` such that all elements satisfy `cond` pure def takeWhile(l: List[a], cond: (a) => bool): List[a] = { pure val result = l.foldl(([], true), (acc, e) => { if (acc._2 and cond(e)) { @@ -303,11 +202,6 @@ module basicSpells { assert(takeWhile([1, 5, 4, 3], (x) => x % 2 == 1) == [1, 5]), } - /// `isPrefixOf(l1, l2)` is true iff `l1` is a prefix of `l2`. - /// - /// - @param l1: a list of any type - /// - @param l2: a list of same type as `l1` - /// - @returns true iff `l1` is a prefix of `l2` pure def isPrefixOf(l1: List[a], l2: List[a]): bool = { if (l1.length() > l2.length()) { false @@ -324,12 +218,6 @@ module basicSpells { assert(isPrefixOf([], [])), } - /// `find(s, f)` is an element of `s` that satisfies the predicate `f`, or None - /// if no such element exists. - /// - /// - @param s: a set of any type - /// - @param f: a function that takes an element of the set and returns a boolean - /// - @returns an element of `s` that satisfies `f`, or None pure def find(s, f) = s.fold(None, (a, i) => if (f(i)) Some(i) else a) run findTest = all { @@ -337,12 +225,6 @@ module basicSpells { assert(find(Set(1, 2, 3), x => x == 4) == None), } - /// `findFirst(l, f)` is the first element of `l` that satisfies the predicate `f`, or None - /// if no such element exists. - /// - /// - @param l: a list of any type - /// - @param f: a function that takes an element of the list and returns a boolean - /// - @returns the first element of `l` that satisfies `f`, or None pure def findFirst(l, f) = l.foldl(None, (a, i) => if (a == None and f(i)) Some(i) else a) run findFirstTest = all { @@ -350,14 +232,6 @@ module basicSpells { assert(findFirst([1, 2, 3], x => x == 4) == None), } - /// `setByWithDefault(m, k, op, default)` is a map that is the same as `m` except that - /// the value associated with `k` is `op(m[k])` if `k` is present in `m`, and `op(default)` otherwise. - /// - /// - @param m: a map from type `a` to type `b` - /// - @param k: a key of type `a` - /// - @param op: a function to transform the value of the key - /// - @param default: the value to use if the key is not present in the map - /// - @returns a new map with the updated key. pure def setByWithDefault(m: a -> b, k: a, op: (b) => b, default: b): a -> b = { if (m.has(k)) m.setBy(k, op) diff --git a/.claude/skills/quint-modeling/examples/tendermint/tendermint.qnt b/.claude/skills/quint-modeling/examples/tendermint/tendermint.qnt index 26dfde0f6..9eba87093 100644 --- a/.claude/skills/quint-modeling/examples/tendermint/tendermint.qnt +++ b/.claude/skills/quint-modeling/examples/tendermint/tendermint.qnt @@ -1,42 +1,3 @@ -/* ============================================================================= - * quint-modeling REFERENCE EXAMPLE — communication model: MESSAGE-PASSING (Choreo) - * ----------------------------------------------------------------------------- - * Why this is bundled: it is the canonical *Choreo framework* spec — a real BFT - * consensus engine (Tendermint), and the source of the examples in - * ../../../quint-lang/guidelines/choreo.md. Choreo is a different programming model - * from plain Quint (its own `choreo::` API), so it cannot be inferred — you have to - * see one. Contrast with the shared-memory example (../ewd426.qnt). - * - * READ THIS when modelling ANY distributed protocol where parties exchange messages — - * consensus/BFT, replication, atomic commit, leader election, reliable broadcast/gossip, - * request/response, a mempool. It is the default reference for message-passing systems - * (not just consensus); the patterns below transfer. Use ../ewd426.qnt instead only when - * parts coordinate through SHARED STATE rather than messages. - * - * Demonstrates the `choreo::cue` PATTERN — separate *when* from *what*: - * - `listen_*(ctx): Set[Params]` — the messages/conditions that match (Set[()] for - * state/quorum-only triggers). - * - `broadcast_*` / `act_*(ctx, p): Transition` — the reaction for each match. - * - `main_listener` wires them with `choreo::cue(ctx, listen, act)` (x7) — reads - * like the protocol at a glance. - * Plus: real `agreement` / `validity` / `accountability` invariants. - * - * QUICK READ (to learn the pattern without reading all ~760 lines — anchored to - * names so it survives upstream re-sync): read `listen_proposal_in_propose` + - * `broadcast_prevote_for_proposal` (one cue pair), then `main_listener` (the wiring), - * then the `agreement` / `validity` / `accountability` invariants. The rest is full - * protocol depth. - * - * TESTS: in the sibling `tendermintTest.qnt` (this spec has no `run`s, per the - * test-separation guideline — quint-lang/guidelines/tests.md). That file also holds - * the concrete instances; the spec here is parametric (const F/CORRECT/FAULTY/...), - * so it cannot run on its own — run an instance: - * quint run tendermintTest.qnt --main=valid --invariant="agreement and validity and accountability" - * The `no_agreement` instance there is a deliberate agreement-violation demo. - * - * Dependencies (bundled alongside): ./choreo.qnt, ./spells/basicSpells.qnt. - * Verified clean on Quint 0.32.0. See ../README.md for re-verification commands. - * ============================================================================= */ module tendermint { import basicSpells.* from "./spells/basicSpells" import choreo(processes = NODES) as choreo from "./choreo" @@ -54,9 +15,6 @@ module tendermint { type TimeoutKind = ProposeTimeout | PreVoteTimeout | PreCommitTimeout type TimeoutEvent = { kind: TimeoutKind, round: Round } - /// The ID of a value. In the implementation, this would be a hash of the value. - /// Here, we wrap it in a record and don't convert it back into a value. - /// This keeps the property that v1.id() == v2.id() iff v1 == v2. type ValueId = { hashed: Value } type Node = str @@ -94,7 +52,6 @@ module tendermint { type Event = TimeoutEvent type Extensions = Bookkeeping - /* Boilerplate */ type LocalState = choreo::LocalState[Node, StateFields] type LocalContext = choreo::LocalContext[Node, StateFields, Message, Event, Extensions] type Transition = choreo::Transition[Node, StateFields, Message, Event, CustomEffects] @@ -105,7 +62,6 @@ module tendermint { Event, Extensions ] - /* End of boilerplate */ pure def get_proposals(messages: Set[Message]): Set[ProposeMsg] = messages.filterMap(m => { @@ -180,13 +136,11 @@ module tendermint { s.stage == ProposeStage } - // Message guards: predicates on the messages that can use the state as context def message_guard = (p) => and { p.valid_round == -1, p.src == PROPOSER.get(s.round), } - // Apply Guards val proposals = messages.get_proposals() proposals.filter(p => and { message_guard(p), @@ -197,14 +151,12 @@ module tendermint { pure def broadcast_prevote_for_proposal(ctx: LocalContext, p: ProposeMsg): Transition = { val s = ctx.state - // Broadcast the PreVote message for the proposal pure val effects = if (valid(p.proposal) and (s.locked_round == -1 or s.locked_value == Some(p.proposal))) { Set(choreo::Broadcast(PreVote({ src: s.process_id, round: s.round, id: Some(id(p.proposal)) }))) } else { Set(choreo::Broadcast(PreVote({ src: s.process_id, round: s.round, id: None }))) } - // TODO -> add timeout and logging effects { post_state: { ...s, stage: PreVoteStage }, effects: effects.setAdd(choreo::CustomEffect(CollectEvidence(Propose(p)))) @@ -232,7 +184,7 @@ module tendermint { val pre_votes = messages.get_pre_votes() proposals.filter(p => and { - pre_votes.filter(q => q.id == Some(p.proposal.id()) and q.round == p.valid_round).size() >= 2 * F + 1 // quorum size is F + 1 + pre_votes.filter(q => q.id == Some(p.proposal.id()) and q.round == p.valid_round).size() >= 2 * F + 1 }) } @@ -240,14 +192,12 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for prevotes that contributed to this decision val contributing_prevotes = messages.get_pre_votes().filter(pv => pv.round == p.valid_round and pv.id == Some(id(p.proposal)) ) val prevote_evidence = contributing_prevotes.map(pv => choreo::CustomEffect(CollectEvidence(PreVote(pv)))) val evidence = Set(choreo::CustomEffect(CollectEvidence(Propose(p)))).union(prevote_evidence) - // Broadcast the PreVote message for the proposal val effects = if (valid(p.proposal) and (s.locked_round <= p.valid_round or s.locked_value == Some(p.proposal))) { Set(choreo::Broadcast(PreVote({ src: s.process_id, round: s.round, id: Some(id(p.proposal))}))) } else { @@ -265,11 +215,10 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Do we have a quorum of PreVotes in the current round def message_guard = (pv) => (pv.round == s.round) val quorum = messages.get_pre_votes().filter(pv => and { message_guard(pv), - }).size() >= 2 * F + 1 // quorum size is F + 1 + }).size() >= 2 * F + 1 if (quorum) { Set(()) @@ -281,7 +230,6 @@ module tendermint { pure def trigger_prevote_timeout(ctx: LocalContext, _params: ()): Transition = { val s = ctx.state - // If we have a quorum, we can move to precommit stage { post_state: s, effects: Set(choreo::TriggerEvent({ kind: PreVoteTimeout, round: s.round })) @@ -296,7 +244,6 @@ module tendermint { s.stage == PreVoteStage, } - // Do we have a quorum of PreVotes in the current round def message_guard = (pv) => (pv.round == s.round and pv.id == None) val prevotes = messages.get_pre_votes().filter(pv => message_guard(pv)) val quorum = prevotes.map(m => m.src).size() >= 2 * F + 1 @@ -312,13 +259,11 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for all nil prevotes that enabled this decision val nil_prevotes = messages.get_pre_votes().filter(pv => pv.round == s.round and pv.id == None ) val prevote_evidence = nil_prevotes.map(pv => choreo::CustomEffect(CollectEvidence(PreVote(pv)))) - // If we have a quorum, we can move to precommit stage { post_state: { ...s, stage: PreCommitStage }, effects: Set( @@ -331,11 +276,10 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Do we have a quorum of PreCommits in the current round def message_guard = (pc) => (pc.round == s.round) val quorum = messages.get_pre_commits().filter(pc => and { message_guard(pc), - }).map(m => m.src).size() >= 2 * F + 1 // quorum size is F + 1 + }).map(m => m.src).size() >= 2 * F + 1 if (quorum) { Set(()) @@ -347,7 +291,6 @@ module tendermint { pure def trigger_precommit_timeout(ctx: LocalContext, _params: ()): Transition = { val s = ctx.state - // If we have a quorum, we can move to decided stage { post_state: s, effects: Set(choreo::TriggerEvent({ kind: PreCommitTimeout, round: s.round })) @@ -373,7 +316,6 @@ module tendermint { proposals.filter(p => and { message_guard(p), state_guard, - // Check for quorum of prevotes for this proposal in current round pre_votes.filter(pv => and { pv.round == s.round, pv.id == Some(id(p.proposal)) @@ -385,16 +327,13 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for prevotes that enabled this decision val enabling_prevotes = messages.get_pre_votes().filter(pv => pv.round == s.round and pv.id == Some(id(p.proposal)) ) val prevote_evidence = enabling_prevotes.map(pv => choreo::CustomEffect(CollectEvidence(PreVote(pv)))) if (s.stage == PreVoteStage) { - // If in prevote stage, broadcast precommit and move to precommit stage { - // Move to precommit stage and update values post_state: { ...s, stage: PreCommitStage, @@ -409,7 +348,6 @@ module tendermint { ).union(prevote_evidence) } } else { - // Just update valid value if already in precommit { post_state: { ...s, @@ -431,7 +369,7 @@ module tendermint { def message_guard = (p) => and { p.src == PROPOSER.get(p.round), - p.round <= s.round // Can decide on current or past rounds + p.round <= s.round } val proposals = messages.get_proposals() @@ -440,7 +378,6 @@ module tendermint { proposals.filter(p => and { message_guard(p), state_guard, - // Check for quorum of precommits for this proposal pre_commits.filter(pc => and { pc.round == p.round, pc.id == Some(id(p.proposal)) @@ -452,13 +389,11 @@ module tendermint { val s = ctx.state val messages = ctx.messages - // Collect evidence for precommits that enabled this decision val enabling_precommits = messages.get_pre_commits().filter(pc => pc.round == p.round and pc.id == Some(id(p.proposal)) ) val precommit_evidence = enabling_precommits.map(pc => choreo::CustomEffect(CollectEvidence(PreCommit(pc)))) - // Make decision and move to decided stage { post_state: { ...s, @@ -564,7 +499,6 @@ module tendermint { } } - // Card(powset) = 4096 val byzantine_messages_1 = { val rounds = Set(0) val byzantine_proposals = rounds.map(r => { @@ -585,21 +519,15 @@ module tendermint { }) }).flatten() - // Reintegrate byzantine proposals Set(byzantine_prevotes, byzantine_precommits, byzantine_proposals).flatten() } - // TODO (Gabriela): I don't understand this val byzantine_messages = { - // We can have at most 2^F faulty nodes, so we take the powerset of the byzantine messages - // to simulate all possible combinations of byzantine messages. - // 10 dummy prevotes for future rounds val dummy_prevotes = 1000.to(1025).map(r => { PreVote({ src: "p4", round: r, id: None }) }) dummy_prevotes - //Set() } action init = choreo::init({ @@ -628,50 +556,6 @@ module tendermint { ) - // -------------------------------- semantic symmetry utilities -------------------------------- - // TODO: Update these functions to work with choreo library - /* - type StateFingerprint = { - round: Round, - stage: Stage, - decision: Option[Value], - locked_value: Option[Value], - locked_round: Round, - valid_value: Option[Value], - valid_round: Round, - after_prevote_for_first_time: bool, - precommit_quorum: bool, - is_proposer: bool, - } - - pure def select_representatives(s: GlobalState): Set[Node] = { - val states = s.system.values() - val unique = group_by_fingerprint(states) - unique.setByAll((k, group) => group.filter(n =>(n.in(CORRECT))).takeOne()). - values().filter(n => n != None).map(n => n.unwrap()) - } - - def group_by_fingerprint(s: Set[LocalState]): StateFingerprint -> Set[Node] = { - val init = Map() - s.fold(init, (acc, state) => { - val key = { - round: state.round, - stage: state.stage, - decision: state.decision, - locked_value: state.locked_value, - locked_round: state.locked_round, - valid_value: state.valid_value, - valid_round: state.valid_round, - after_prevote_for_first_time: state.after_prevote_for_first_time, - precommit_quorum: state.precommit_quorum, - is_proposer: state.process_id == PROPOSER.get(state.round) - } - acc.setByWithDefault(key, (e) => e.setAdd(state.process_id),Set()) - }) - } - */ - // -------------------------------- semantic symmetry utilities -------------------------------- - val correct_nodes = s.system.values().filter(s => s.process_id.in(CORRECT)) val agreement = tuples(correct_nodes, correct_nodes).forall(((p1, p2)) => { p1.decision == None or p2.decision == None or p1.decision == p2.decision @@ -683,8 +567,6 @@ module tendermint { val all_decided = not(correct_nodes.exists(v => v.decision == None)) - // Witness for a to find a case where a node is in the decided stage while another is prevote - // state val stages = and { s.system.values().map(v => v.stage).contains(ProposeStage), @@ -693,15 +575,12 @@ module tendermint { s.system.values().map(v => v.stage).contains(DecidedStage) } - // Evidence-based properties - pure def equivocation_in(n: Node, evidence: Set[{ src: Node, round: Round | other }]): bool = { tuples(evidence, evidence).exists(((e1, e2)) => { e1 != e2 and e1.src == n and e2.src == n and e1.round == e2.round }) } - /// Equivocation by a node n def equivocation_by(n: Node): bool = { or { n.equivocation_in(s.extensions.evidence_propose), @@ -710,7 +589,6 @@ module tendermint { } } - /// Amnesic behavior by a node n def amnesia_by(n: Node): bool = { tuples(ROUNDS, ROUNDS).exists(((r1, r2)) => { r1 < r2 and tuples(VALID_VALUES, VALID_VALUES).exists(((v1, v2)) => { @@ -732,12 +610,8 @@ module tendermint { }) } - /// Validity: the decided block satisfies the predefined predicate valid(). val validity = correct_nodes.forall(s => s.decision.in(VALID_VALUES.map(v => Some(v)).setAdd(None))) - /// The protocol safety. Two cases are possible: - /// 1. There is no fork, that is, Agreement holds true. - /// 2. A subset of faulty processes demonstrates equivocation or amnesia. val accountability = or { agreement, FAULTY.powerset().exists(f => and { @@ -747,24 +621,15 @@ module tendermint { } const F: int - /// The set of correct processes const CORRECT: Set[Node] - /// The set of faulty processes const FAULTY: Set[Node] - /// Which node is the proposer in each round const PROPOSER: Round -> Node - /// Which value is proposed in each round. - /// Values from rounds with correct nodes (in PROPOSER) are considered valid values. const VALUES: Round -> Value const MAX_ROUND: Round - /// The set of all nodes pure val NODES = CORRECT.union(FAULTY) - /// The set of all rounds (prepared by the constants) pure val ROUNDS = VALUES.keys() - /// The set of all correct values (prepared by the constants) - //pure val VALID_VALUES = ROUNDS.filter(k => PROPOSER.get(k).in(CORRECT)).map(k => VALUES.get(k)) pure val VALID_VALUES = Set("v0", "v1", "v2") action step_with(v: Node, listener: LocalContext => Set[Transition]): bool = diff --git a/.claude/skills/quint-modeling/examples/tendermint/tendermintTest.qnt b/.claude/skills/quint-modeling/examples/tendermint/tendermintTest.qnt index 8d0cc8a2d..0d05372a0 100644 --- a/.claude/skills/quint-modeling/examples/tendermint/tendermintTest.qnt +++ b/.claude/skills/quint-modeling/examples/tendermint/tendermintTest.qnt @@ -1,24 +1,4 @@ -/* ============================================================================= - * Tests for the Tendermint Choreo reference example. - * - * Per the test-separation guideline (quint-lang/guidelines/tests.md), `run` tests - * live in this file, NOT in the spec — `tendermint.qnt` has no `run` definitions. - * Each module here instantiates the parametric `tendermint` spec with concrete - * consts (the const-instantiation pattern) and drives a scenario: - * - `valid` — a run where consensus succeeds; `line28Test` exercises the - * proposal/prevote/precommit cue chain across a round change. - * - `no_agreement` — a faulty proposer equivocates; `disagreementTest` shows the - * `agreement` invariant being violated (a counterexample demo). - * - * Run / test (from this directory): - * quint run tendermintTest.qnt --main=valid --invariant="agreement and validity and accountability" - * quint test tendermintTest.qnt --main=valid - * quint run tendermintTest.qnt --main=no_agreement --invariant=accountability - * quint test tendermintTest.qnt --main=no_agreement - * ============================================================================= */ module valid { - // quint run tendermintTest.qnt --main valid --invariant="agreement and validity and accountability" - // quint test tendermintTest.qnt --main valid import basicSpells.* from "./spells/basicSpells" @@ -44,10 +24,8 @@ module valid { .then("p2".with_cue(listen_quorum_precommits_any, ()).perform(trigger_precommit_timeout)) .then(step_with("p2", on_precommit_timeout)) - // p2 starts a new round .expect(s.system.get("p2").round == 1) - // since p2 is the proposer in the new round, it will propose the stored valid value .expect(and { s.system.get("p2").stage == ProposeStage, s.messages.values().forall(ms => { @@ -55,8 +33,6 @@ module valid { }) }) - // Which enables line 28 to be called by p2, as it is in propose stage and can receive - // the new proposal with valid_round 0. .then("p2" .with_cue(listen_proposal_in_propose_prevote, { proposal: "v0", round: 1, src: "p2", valid_round: 0 }) .perform(broadcast_prevote_with_validation) @@ -65,18 +41,11 @@ module valid { } module no_agreement { - // Should fail: - // quint run tendermintTest.qnt --main no_agreement --invariants=agreement validity accountability - // - // Should succeed (accountability should still hold): - // quint run tendermintTest.qnt --main no_agreement --invariant=accountability - // quint test tendermintTest.qnt --main no_agreement import tendermint( F = 1, CORRECT = Set("p1", "p2"), FAULTY = Set("p3","p4"), - // a faulty node is the proposer in the first round PROPOSER = Map(0 -> "p3", 1 -> "p2", 2 -> "p3", 3 -> "p4"), VALUES = Map(0 -> "v0", 1 -> "v1", 2 -> "v2", 3 -> "v3"), MAX_ROUND = 4 diff --git a/.opencode/plugins/sce-agent-trace.ts b/.opencode/plugins/sce-agent-trace.ts index c57c3e603..214a09c41 100644 --- a/.opencode/plugins/sce-agent-trace.ts +++ b/.opencode/plugins/sce-agent-trace.ts @@ -89,7 +89,6 @@ function extractDiffTracePayload( event: EventMessageUpdated, ): DiffTracePayload | undefined { const eventInfo = event.properties.info; - // Only capture user messages (filter out assistant, system, etc.) if (eventInfo.role !== "user") { return undefined; } @@ -334,9 +333,6 @@ async function runDiffTraceHook( await new Promise((resolve) => { const child = spawn("sce", ["hooks", "diff-trace"], { cwd: repoRoot, - // Fail-open: stderr is ignored so that sce intake errors - // (connection refused, timeout, etc.) do not leak into the - // OpenCode TUI. Resolve unconditionally on any outcome. stdio: ["pipe", "ignore", "ignore"], }); @@ -359,9 +355,6 @@ async function runConversationTraceHook( await new Promise((resolve) => { const child = spawn("sce", ["hooks", "conversation-trace"], { cwd: repoRoot, - // Fail-open: stderr is ignored so that sce intake errors - // (connection refused, timeout, etc.) do not leak into the - // OpenCode TUI. Resolve unconditionally on any outcome. stdio: ["pipe", "ignore", "ignore"], }); diff --git a/.opencode/plugins/sce-bash-policy.ts b/.opencode/plugins/sce-bash-policy.ts index 0b2b8d9c9..03cf59326 100644 --- a/.opencode/plugins/sce-bash-policy.ts +++ b/.opencode/plugins/sce-bash-policy.ts @@ -13,11 +13,6 @@ interface JsonPolicyResult { const SCE_INSTALL_URL = "https://sce.crocoder.dev/docs/getting-started#install-cli"; -/** - * Evaluate a bash command against SCE bash-tool policy by delegating to the - * Rust `sce policy bash` command. Returns the parsed JSON result, or null if - * the policy check could not be performed (fail-open). - */ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null { try { const result = spawnSync( @@ -72,7 +67,6 @@ export const SceBashPolicyPlugin: Plugin = async () => { const policyResult = evaluateBashCommandPolicy(command); if (!policyResult) { - // Fail open: if the policy check cannot be performed, allow the command. return; } diff --git a/.pi/extensions/sce/index.ts b/.pi/extensions/sce/index.ts index 54cb2576c..bd4311a62 100644 --- a/.pi/extensions/sce/index.ts +++ b/.pi/extensions/sce/index.ts @@ -94,11 +94,6 @@ type PendingFileMutation = { before: string | undefined; }; -/** - * Evaluate a bash command against SCE bash-tool policy by delegating to the - * Rust `sce policy bash` command. Returns the parsed JSON result, or null if - * the policy check could not be performed (fail-open). - */ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null { try { const result = spawnSync( @@ -134,11 +129,6 @@ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null { } } -/** - * Send a conversation-trace payload to `sce hooks conversation-trace`, - * fire-and-forget. Fail-open: stderr is ignored so that sce intake errors do - * not leak into the Pi TUI, and the returned promise never rejects. - */ function runConversationTraceHook( cwd: string, payload: ConversationTracePayload, @@ -228,12 +218,6 @@ function buildMessageEndConversationTracePayload( return { tool_name: TOOL_NAME, payloads }; } -/** - * Resolve the installed Pi package version for diff-trace `tool_version`. - * The package's `exports` map does not expose `package.json`, so resolve the - * package entry point and read `package.json` from the package root instead. - * Returns null when resolution fails (normalized diff traces permit it). - */ async function resolvePiToolVersion(): Promise { try { const entryPath = fileURLToPath( @@ -251,10 +235,6 @@ async function resolvePiToolVersion(): Promise { } } -/** - * Send a diff-trace payload to `sce hooks diff-trace`, fire-and-forget. - * Fail-open: stderr is ignored and the returned promise never rejects. - */ function runDiffTraceHook( cwd: string, payload: DiffTracePayload, @@ -292,11 +272,6 @@ function diffLabelFor(cwd: string, absolutePath: string): string { : absolutePath; } -/** - * Rewrite temp-file path labels in git diff header lines to the repo-relative - * target path. Only header lines before the first `@@` hunk marker are - * touched so that content lines starting with `--- ` / `+++ ` are preserved. - */ function rewriteDiffLabels( diff: string, label: string, @@ -319,12 +294,6 @@ function rewriteDiffLabels( return lines.join("\n"); } -/** - * Produce a unified diff between before/after contents by writing them to - * temp files and spawning `git diff --no-index --no-ext-diff` (exit status 1 - * means "files differ"). Returns undefined for no-op diffs or any failure; - * temp files are always cleaned up. - */ async function buildUnifiedDiff( label: string, before: string | undefined, @@ -775,7 +744,6 @@ export default function sceExtension(pi: ExtensionAPI): void { const policyResult = evaluateBashCommandPolicy(command); if (!policyResult) { - // Fail open: if the policy check cannot be performed, allow the command. return undefined; } diff --git a/AGENTS.md b/AGENTS.md index 4b0c8b899..bb3c907f1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,263 +1,8 @@ -# AGENTS.md +## Comments in code -This file is for coding agents working in this repository. -It summarizes the commands, workflows, and code conventions that are visible in the current codebase. +Prefer clear names and structure over comments. Add comments only to explain non-obvious constraints, invariants, or behavior that the code cannot express clearly. Keep broader design rationale and implementation history in SCE context. Never use code comments to narrate changes, describe previous implementations, or maintain change logs. -This repository uses the Shared Context Engineering (SCE) approach for AI-assisted software delivery with explicit, versioned context: `https://sce.crocoder.dev/` +## Rust conventions -## Repository shape - -- Root repo contains three main working areas: -- `cli/` - Rust CLI (`sce`) -- `config/` - generated agent config, skills, and Pkl sources -- `context/` - shared context docs, plans, decisions, and handovers - -## Rule files checked - -- Root agent guidance lives in this `AGENTS.md`. -- Bash command policies live in `.sce/config.json` under `policies.bash.custom` (enforced by the SCE bash-policy plugin). -- No `.cursor/rules/` directory was found. -- No `.cursorrules` file was found. -- No `.github/copilot-instructions.md` file was found. -- If any of those files are added later, update this document to fold their instructions in. - -## How to run commands (agents) - -**Default rule:** host `coreutils` / POSIX basics are fine as-is. **Everything else must go through Nix** — do not assume `rg`, `jq`, `bun`, `python3`, `node`, `cargo`, etc. are on the host `PATH`. - -### Allowed without Nix - -Use the host shell for ordinary shell built-ins and common coreutils-style tools, for example: - -- shell: `cd`, `export`, `true`, `false`, pipelines, redirections -- coreutils-ish: `ls`, `cat`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `ln`, `head`, `tail`, `sort`, `uniq`, `wc`, `cut`, `tr`, `tee`, `echo`, `printf`, `test`, `[`, `basename`, `dirname`, `realpath`, `pwd`, `env`, `xargs`, `find` (when already available) -- git (repo workflows), and `nix` itself - -### Non-coreutils → Nix - -For any other CLI (`rg`, `fd`, `jq`, `yq`, `bun`, `node`, `python3`, `shellcheck`, `actionlint`, `hyperfine`, language toolchains, etc.), run it via one of: - -| Pattern | When to use | Example | -| --- | --- | --- | -| `nix develop -c …` | Repo flake tools (Rust toolchain, Bun, Pkl from this project’s dev shell) | `nix develop -c sh -c 'cd cli && cargo build'` | -| `nix shell nixpkgs#pkg -c …` | One-shot tool from nixpkgs (preferred for policy-satisfied ad-hoc tools) | `nix shell nixpkgs#ripgrep -c rg pattern path` | -| `nix run nixpkgs#pkg -- …` | Alternate one-shot form | `nix run nixpkgs#jq -- . file.json` | -| `nix run .#attr -- …` | Flake apps / checks defined in this repo | `nix run .#pkl-check-generated` | -| `nix flake check` | Default full verification | Prefer this over raw `cargo test` / `cargo check` / `cargo fmt --check` | - -Repo bash policy (`.sce/config.json`) already blocks bare invocations of several tools and steers agents to Nix. Known policy-covered tools: - -- **Cargo verification:** prefer `nix flake check` over bare `cargo test`, `cargo check`, and `cargo fmt --check`. Keep `cargo fmt` (autofix) only through `nix develop`. -- **Ad-hoc tools via Nix:** `rg` → `nixpkgs#ripgrep`, `jq` → `nixpkgs#jq`, `python3` → `nixpkgs#python3`, `node` → `nixpkgs#nodejs`, `bun` → `nixpkgs#bun` (or repo `nix develop`), `fd` → `nixpkgs#fd`, `shellcheck` → `nixpkgs#shellcheck`, `actionlint` → `nixpkgs#actionlint`, `yq` → `nixpkgs#yq-go`, `hyperfine` → `nixpkgs#hyperfine`. - -If a tool is not listed above but is not coreutils, still run it through `nix shell` / `nix run` / `nix develop` the same way. Do not install host packages to work around missing binaries. - -### Choosing the right Nix entrypoint - -1. **Repo work (Rust CLI, Bun plugin, flake tools):** `nix develop -c sh -c '…'` from repo root. -2. **Single external utility:** `nix shell nixpkgs# -c …` or `nix run nixpkgs# -- …`. -3. **Validation / CI parity:** `nix flake check` (and `nix run .#pkl-check-generated` when touching generated config). - -## Tooling and environment - -- Nix is the primary reproducible entrypoint at repo root. -- Root `flake.nix` provides Bun, TypeScript, Pkl, jq, and the Rust toolchain. -- Root `flake.nix` defines Crane-based Rust packaging and check derivations for the CLI. -- Run Cargo via Nix, not directly from the host shell. Prefer `nix develop -c sh -c 'cd cli && '`. -- For validation, prefer `nix flake check` and avoid running `cargo test` / `cargo check` / `cargo fmt --check` directly unless a user explicitly requests it. -- Optional local Nix tuning can live in user-level `~/.config/nix/nix.conf`; recommended values are `max-jobs = auto` and `cores = 0`. -- `auto-optimise-store = true` is intentionally treated as a system-level `/etc/nix/nix.conf` setting, not a repo-managed user setting. -- Bun is used for repo-owned config/plugin workflows; prefer Bun rather than npm or pnpm scripts when working in those areas. Always invoke Bun through Nix (`nix develop` or `nix shell nixpkgs#bun`). -- Rust edition is `2021`. -- TypeScript is still used in repo-owned config/plugin sources and should remain strict-mode friendly. - -## High-value commands - -### Root-level setup - -- Enter dev shell: `nix develop` -- Run all flake checks visible at root: `nix flake check` -- Run generated-output parity check: `nix run .#pkl-check-generated` - -### Rust CLI commands - -Run these through Nix from repo root unless noted otherwise. - -- Build CLI: `nix develop -c ./scripts/run-cli-cargo.sh build --manifest-path cli/Cargo.toml` -- Run CLI: `nix develop -c ./scripts/run-cli-cargo.sh run --manifest-path cli/Cargo.toml -- --help` -- Build packaged CLI output: `nix build .#default` -- Run packaged CLI app: `nix run .#sce -- --help` -- Preferred repo-level verification: `nix flake check` -- Run a single Rust test by exact name when explicitly needed: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml parser_routes_mcp -- --exact` -- Run Rust tests in one module/file pattern when explicitly needed: `nix develop -c ./scripts/run-cli-cargo.sh test --manifest-path cli/Cargo.toml setup` -- Run pre-Cargo wrapper tests: `bash scripts/test-run-cli-cargo.sh` -- Run ignored? none were found; do not assume ignored-test flows exist. -- Rust format verification is covered by `nix flake check` -- Auto-format only (not verification): `nix develop -c sh -c 'cd cli && cargo fmt'` -- Rust lint verification is covered by `nix flake check` - -### Bun config/plugin commands - -Run from repo root through Nix (do not call bare `bun` on the host). Working directory for the plugin tests is `config/lib/bash-policy-plugin/`. - -- Run plugin/runtime test suite: `nix develop -c sh -c 'cd config/lib/bash-policy-plugin && bun test'` -- Run a single Bun test by name: `nix develop -c sh -c 'cd config/lib/bash-policy-plugin && bun test -t ""'` -- One-shot Bun without the full flake shell: `nix shell nixpkgs#bun -c bun test` (run after `cd` into the plugin dir) - -### Useful combined validation flows - -- Preferred repo validation from repo root: `nix flake check` -- Config/plugin validation from repo root: `nix develop -c sh -c 'cd config/lib/bash-policy-plugin && bun test'` -- Generated-config validation from repo root: `nix run .#pkl-check-generated` - -### Reading SCE Turso databases - -- This repository no longer packages a Turso CLI (removed from `flake.nix` in `1b84a0b1`); there is no `nix run .#turso`. Use a Turso shell (`turso` / `tursodb`) whose `--version` matches the `turso` crate version in `cli/Cargo.lock` (currently `0.8.1`). Do not use a host `sqlite3`, nixpkgs `limbo` (older on-disk format), or nixpkgs `turso-cli` (the Turso Cloud CLI, not a database shell). If no matching shell is available, ask the user before inspecting with anything else. -- Discover the active repository-scoped Agent Trace DB with `nix run .#sce -- doctor --format json` and read `agent_trace_db.path`. Do not guess the repository ID or inspect legacy `/sce/agent-trace.db` / `agent-trace-.db` files; active storage is `/sce/repos//agent-trace.db`. -- Always enable Turso's multiprocess WAL coordination when opening an SCE database that may also be used by hooks or another agent process: `turso --experimental-multiprocess-wal --readonly ""`. -- Prefer `--readonly` for inspection. Add a SQL argument for non-interactive reads, for example: `turso --experimental-multiprocess-wal --readonly "" "PRAGMA quick_check;"`. Add `-m list` for pipe-separated output that is easier to post-process. -- Verify the connection before interpreting data: run `PRAGMA quick_check;` (expect `ok`), `PRAGMA journal_mode;` (expect `wal`), and `SELECT id, applied_at FROM __sce_migrations ORDER BY id;`. -- Useful Agent Trace checks include `SELECT COUNT(*) FROM agent_traces;`, `SELECT COUNT(*) FROM messages;`, `SELECT COUNT(*) FROM parts;`, and `SELECT actor_kind, status, COUNT(*) FROM mutation_trace_scopes GROUP BY actor_kind, status;`. -- Concurrent inspection processes may temporarily appear as active OpenCode `bash` mutation scopes because the query command itself is a tracked tool call. After the commands finish, `.git/sce/opencode-mutation-scope-state.json` should normally show `"attempts": []` and a clear recovery phase. -- Do not copy only `agent-trace.db` for inspection while writers are active: committed data may still be represented through WAL state. Open the canonical path with `--experimental-multiprocess-wal`, or stop all writers before making a database snapshot. - -### Ad-hoc tool examples (non-coreutils) - -- Ripgrep: `nix shell nixpkgs#ripgrep -c rg ` -- jq: `nix shell nixpkgs#jq -c jq . file.json` -- Python: `nix shell nixpkgs#python3 -c python3 script.py` -- Node: `nix shell nixpkgs#nodejs -c node script.js` -- fd: `nix shell nixpkgs#fd -c fd ` -- shellcheck: `nix shell nixpkgs#shellcheck -c shellcheck script.sh` -- actionlint: `nix shell nixpkgs#actionlint -c actionlint` -- yq: `nix shell nixpkgs#yq-go -c yq . file.yaml` -- hyperfine: `nix shell nixpkgs#hyperfine -c hyperfine ''` - -## Testing notes - -- Rust tests live inline in source files and in module test files such as `cli/src/services/mutation_trace/mbt/tests.rs`. -- Repository Cargo builds must use `scripts/run-cli-cargo.sh`; it generates a fresh temporary Pkl payload, passes `SCE_CLI_GENERATED_INPUT_DIR` to Cargo, and cleans up the payload afterward. -- Rust/Cargo commands should be executed through `nix develop`, even for one-off builds, tests, fmt, and clippy runs. -- Prefer `nix flake check` for routine verification and avoid bare `cargo test` / `cargo check` / `cargo fmt --check` unless the user explicitly asks. -- Rust single-test selection uses standard Cargo substring matching; add `-- --exact` for deterministic one-test runs. -- Bun tests use `bun:test` and support `-t` name filtering; always launch Bun via Nix. -- Bun/plugin tests under `config/lib/bash-policy-plugin/` are lighter-weight repo validation and remain part of the flake check surface. - -## CI and release hints - -- Release builds generate assistant payloads from canonical `config/pkl/` sources; crates.io and Flatpak stage packaging-only fallbacks in temporary or ignored locations. -- Root `flake.nix` packages `sce` through Crane's `buildDepsOnly` + `buildPackage` pipeline and runs `cli-tests`, `cli-clippy`, and `cli-fmt` through Crane-backed checks. -- Changes to Pkl generation inputs require `nix run .#pkl-check-generated`; generated OpenCode, Claude, and Pi target trees are not committed. - -## Code style: general - -- Follow existing local patterns before introducing new abstractions. -- Keep changes scoped and incremental. -- Prefer deterministic behavior and stable output text; this matters in CLI tests. -- Use explicit constants for repeated strings, timeouts, intervals, exit codes, and numeric formatting. -- Prefer small helper functions when they improve readability of branching or setup code. -- Avoid introducing framework-heavy patterns; this repo is mostly plain Rust, Bun, shell, and config assets. - -## Code style: imports - -### Rust imports - -- Group imports in this order: standard library, third-party crates, then `crate::...` imports. -- Use grouped `std` imports such as `use std::path::{Path, PathBuf};`. -- Prefer explicit imported items over wildcard imports. -- Keep import lists stable and reasonably compact. - -### TypeScript imports - -- Use ESM `import` syntax only. -- Keep imports grouped: Node builtins, external packages, then local files. -- Use `type` imports inline where appropriate, for example `import { foo, type Bar } from "pkg";`. -- Use explicit relative file paths like `./test-setup`. - -## Code style: formatting - -- Rust formatting is delegated to `rustfmt`; do not hand-format against it. -- Rust uses 4-space indentation. -- TypeScript uses 2-space indentation, semicolons, trailing commas where multiline, and double-quoted strings in the repo's remaining TS-owned areas. -- Shell scripts use `#!/usr/bin/env bash` and `set -euo pipefail`. -- Quote shell expansions unless you intentionally need word splitting. -- Prefer readable multi-line expressions over dense one-liners. - -## Code style: types and data modeling - -- In Rust, prefer strong enums and structs for command requests, runtime state, and result payloads. -- Derive common traits explicitly; common order in this repo is `Clone, Copy, Debug, Eq, PartialEq` when applicable. -- In TypeScript, prefer named `type` aliases for payloads and test result structures. -- Keep strict-mode friendliness: handle `undefined`, use narrow unions, and avoid implicit any. -- Prefer explicit return types on exported TypeScript helpers. -- Keep data structures serialization-friendly when they are written to JSON or surfaced by CLI output. - -## Code style: naming - -- Rust types and enums: `UpperCamelCase`. -- Rust functions, modules, and variables: `snake_case`. -- Rust constants: `SCREAMING_SNAKE_CASE`. -- TypeScript types: `PascalCase`. -- TypeScript variables and functions: `camelCase`. -- Test names are descriptive, behavior-oriented, and usually sentence-like with underscores in Rust. -- Prefer names that encode intent, not implementation trivia. - -## Code style: error handling - -- Rust uses `anyhow::Result` broadly for service-layer operations. -- Add context to I/O and process failures with `Context` / `with_context`. -- Use `bail!` and `anyhow!` for concise early exits when appropriate. -- Preserve user-facing diagnostics as stable strings when tests assert on them. -- Separate machine classification from rendered messages when the CLI contract cares about exit codes. -- In TypeScript, throw `Error` with direct, actionable messages. -- Convert unknown thrown values with helper functions like `getErrorMessage` before logging or persisting. - -## Code style: CLI and output contracts - -- Keep stdout reserved for intended command payloads. -- Keep errors on stderr and preserve stable prefixes/codes when existing code does so. -- Do not casually rewrite help text, error phrasing, or JSON field names; tests may depend on exact wording. -- Prefer deterministic ordering in rendered collections, embedded asset lists, and discovered file paths. - -## Code style: tests - -- Add unit tests close to the code they exercise. -- Match the repo's current pattern of focused behavioral test names. -- Assert on exact output when the CLI contract is supposed to be stable. -- For filesystem or manifest checks, sort collected paths before asserting. -- Keep tests isolated; clean up temporary state and abort long-running resources in teardown. - -## Code style: shell and generated config workflows - -- Shell scripts should fail fast, validate prerequisites early, and print concrete remediation steps. -- Prefer staging-and-swap workflows for generated config updates instead of in-place mutation. -- Treat repository-root `.opencode/` as runtime-managed and keep `config/.opencode`, `config/.claude`, `config/.pi`, and `cli/assets/generated/` absent. -- Edit canonical Pkl and `config/lib` authoring sources rather than temporary generated outputs. - -## Working safely as an agent - -- Check for unrelated worktree changes before broad edits. -- Avoid destructive git commands unless the user explicitly asks for them. -- When touching canonical generation inputs, verify ephemeral output with `nix run .#pkl-check-generated`; do not regenerate target trees into the repository. -- When verifying changes, prefer `nix flake check` instead of bare `cargo test` / `cargo check`. -- When changing Bun-owned config/plugin code, run the narrowest Bun test or script that covers the change — always through Nix. -- Do not run non-coreutils CLIs from the host PATH; use `nix develop`, `nix shell`, or `nix run` (see **How to run commands**). - -## Recommended minimum verification by change type - -- Default verification for code changes: `nix flake check` -- Bun/TypeScript config-plugin change: `nix develop -c sh -c 'cd config/lib/bash-policy-plugin && bun test -t ""'` -- Generated config or Pkl change: `nix run .#pkl-check-generated` -- Cross-cutting repo change: `nix flake check` - -## File references worth checking - -- `README.md` -- `flake.nix` -- `context/context-map.md` -- `context/overview.md` -- `cli/Cargo.toml` -- `cli/src/app.rs` -- `config/lib/bash-policy-plugin/package.json` -- `config/lib/bash-policy-plugin/bash-policy-runtime.test.ts` -- `config/lib/bash-policy-plugin/opencode-bash-policy-plugin.ts` +- Prefer static dispatch through concrete types, generics, and enums. Use dynamic dispatch (`dyn Trait`) only when a concrete requirement justifies it. +- Prefer explicit, typed errors with meaningful variants over `anyhow::Error`. Preserve underlying causes where relevant. Use `anyhow` only when typed errors provide no meaningful benefit. diff --git a/cli/assets/hooks/commit-msg b/cli/assets/hooks/commit-msg index 13c85d5ad..c8088cf96 100644 --- a/cli/assets/hooks/commit-msg +++ b/cli/assets/hooks/commit-msg @@ -1,12 +1,10 @@ #!/bin/sh set -eu -# >>> sce managed block (do not edit) >>> if ! command -v sce >/dev/null 2>&1; then - # sce brand colors — only emit ANSI when stderr is a real terminal if [ -t 2 ]; then - RED="$(printf '\033[38;2;220;38;38m')" # red #dc2626 - G="$(printf '\033[38;2;5;150;105m')" # brand green #059669 + RED="$(printf '\033[38;2;220;38;38m')" + G="$(printf '\033[38;2;5;150;105m')" BOLD="$(printf '\033[1m')" R="$(printf '\033[0m')" else @@ -29,4 +27,3 @@ fi sce hooks commit-msg "$@" status=$? exit "$status" -# <<< sce managed block <<< diff --git a/cli/assets/hooks/post-commit b/cli/assets/hooks/post-commit index 7cb1579e8..601f3e003 100644 --- a/cli/assets/hooks/post-commit +++ b/cli/assets/hooks/post-commit @@ -1,12 +1,10 @@ #!/bin/sh set -eu -# >>> sce managed block (do not edit) >>> if ! command -v sce >/dev/null 2>&1; then - # sce brand colors — only emit ANSI when stderr is a real terminal if [ -t 2 ]; then - RED="$(printf '\033[38;2;220;38;38m')" # red #dc2626 - G="$(printf '\033[38;2;5;150;105m')" # brand green #059669 + RED="$(printf '\033[38;2;220;38;38m')" + G="$(printf '\033[38;2;5;150;105m')" BOLD="$(printf '\033[1m')" R="$(printf '\033[0m')" else @@ -35,4 +33,3 @@ else fi status=$? exit "$status" -# <<< sce managed block <<< diff --git a/cli/assets/hooks/pre-commit b/cli/assets/hooks/pre-commit index e9890971e..10da16bf8 100644 --- a/cli/assets/hooks/pre-commit +++ b/cli/assets/hooks/pre-commit @@ -1,12 +1,10 @@ #!/bin/sh set -eu -# >>> sce managed block (do not edit) >>> if ! command -v sce >/dev/null 2>&1; then - # sce brand colors — only emit ANSI when stderr is a real terminal if [ -t 2 ]; then - RED="$(printf '\033[38;2;220;38;38m')" # red #dc2626 - G="$(printf '\033[38;2;5;150;105m')" # brand green #059669 + RED="$(printf '\033[38;2;220;38;38m')" + G="$(printf '\033[38;2;5;150;105m')" BOLD="$(printf '\033[1m')" R="$(printf '\033[0m')" else @@ -29,4 +27,3 @@ fi sce hooks pre-commit "$@" status=$? exit "$status" -# <<< sce managed block <<< diff --git a/cli/build.rs b/cli/build.rs index c20036677..6102e40d5 100644 --- a/cli/build.rs +++ b/cli/build.rs @@ -50,8 +50,6 @@ const TARGETS: &[TargetSpec] = &[ TargetSpec { const_name: "CODEX_EMBEDDED_ASSETS", generated_root: CODEX_TARGET_DIR, - // Not wired into any SetupTarget/install path yet (T05); only read by - // this task's own test so far. allow_dead_code: true, }, TargetSpec { @@ -61,9 +59,6 @@ const TARGETS: &[TargetSpec] = &[ }, ]; -/// Build-time-only staging directory (inside `OUT_DIR`) that merges Codex's two -/// Pkl-generated output roots, `config/.agents` and `config/.codex`, into one -/// tree so it can be embedded like every other single-root target below. const CODEX_TARGET_DIR: &str = "config/codex-target"; const CODEX_AGENTS_SOURCE_DIR: &str = "config/.agents"; const CODEX_HOOKS_SOURCE_DIR: &str = "config/.codex"; @@ -95,9 +90,6 @@ fn prepare_build_artifacts() -> io::Result<()> { if repository_sources_available(repository_root) { println!("cargo:rerun-if-env-changed={GENERATED_INPUT_ENV}"); println!("cargo:rerun-if-env-changed={PACKAGE_FALLBACK_ENV}"); - // Sandboxed source builds (Flatpak) compile a full repository checkout - // without Pkl, so they stage the packaging fallback and opt into it - // explicitly. Every other repository build must supply the handoff. if package_fallback_requested(env::var_os(PACKAGE_FALLBACK_ENV))? { stage_packaged_fallback(&manifest_dir, &out_dir)?; } else { @@ -363,11 +355,6 @@ fn stage_static_inputs( ) } -/// Merges Codex's two Pkl-generated output roots into `CODEX_TARGET_DIR` so it -/// can be embedded through the same single-root `TargetSpec` mechanism as every -/// other target. Runs after both the repository-source and packaged-fallback -/// staging branches, since either one populates the generated payload this -/// reads from. fn stage_codex_target(out_dir: &Path) -> io::Result<()> { let pkl_output_root = out_dir.join(PKL_OUTPUT_DIR); let destination_root = pkl_output_root.join(CODEX_TARGET_DIR); @@ -478,9 +465,6 @@ fn generate_embedded_asset_manifest(out_dir: &Path) -> io::Result<()> { output_file.write_all(output.as_bytes()) } -/// Projects the generated optional-workflow manifest into a Rust catalog so the -/// CLI carries optional workflow identity without re-declaring it. Pkl stays the -/// single source: adding an optional workflow to the catalog is enough. fn generate_optional_workflow_catalog(out_dir: &Path) -> io::Result<()> { let manifest_path = out_dir .join(PKL_OUTPUT_DIR) diff --git a/cli/migrations/agent-trace-repository/001_repository_schema.sql b/cli/migrations/agent-trace-repository/001_repository_schema.sql index e1a61f32e..a1aff98e9 100644 --- a/cli/migrations/agent-trace-repository/001_repository_schema.sql +++ b/cli/migrations/agent-trace-repository/001_repository_schema.sql @@ -1,13 +1,3 @@ --- Repository-scoped Agent Trace database baseline. --- --- One logical Git repository maps to one database at --- /sce/repos//agent-trace.db. This file is the --- complete fresh schema for that database: repository-scoped databases are --- always created new, so the baseline stays a single file instead of an --- incremental migration chain. Trace tables are repository-level and --- intentionally carry no checkout_id columns; checkout identity is --- diagnostics-only context and is never persisted on trace rows. - CREATE TABLE IF NOT EXISTS repository_metadata ( id INTEGER PRIMARY KEY CHECK (id = 1), repository_id TEXT NOT NULL, diff --git a/cli/migrations/agent-trace-repository/002_repository_source_instance_id.sql b/cli/migrations/agent-trace-repository/002_repository_source_instance_id.sql index e47c54e98..9fc15df59 100644 --- a/cli/migrations/agent-trace-repository/002_repository_source_instance_id.sql +++ b/cli/migrations/agent-trace-repository/002_repository_source_instance_id.sql @@ -1,10 +1,2 @@ --- Adds a physical-database identity alongside the existing logical --- repository_id. source_instance_id identifies one physical --- agent-trace.db lineage; it is generated exactly once per database by --- application code, never by SQL, and stays stable across reopen and --- setup reruns. Existing/placeholder rows default to an empty string, --- which application code recognizes as "not yet claimed" and replaces --- through a concurrency-safe atomic claim. - ALTER TABLE repository_metadata ADD COLUMN source_instance_id TEXT NOT NULL DEFAULT ''; diff --git a/cli/migrations/agent-trace-repository/004_mutation_trace_protocol.sql b/cli/migrations/agent-trace-repository/004_mutation_trace_protocol.sql index a4657e4e3..28719f7f7 100644 --- a/cli/migrations/agent-trace-repository/004_mutation_trace_protocol.sql +++ b/cli/migrations/agent-trace-repository/004_mutation_trace_protocol.sql @@ -1,16 +1,3 @@ --- Durable persistence for the verified mutation-cursor protocol --- (`cli/src/services/mutation_trace/`). --- --- This migration is additive: it introduces five new tables and leaves every --- table from 001/002 untouched. `revision` is stored as an 8-byte --- big-endian BLOB on every column that carries one (never a SQLite INTEGER), --- enforced by `CHECK (typeof(revision) = 'blob' AND length(revision) = 8)`, --- so a TEXT value of matching length is still rejected. Enum-shaped columns --- use TEXT with an explicit CHECK allow-list, matching the `role`/ --- `payload_type` convention already used in 001. `AttemptState` (transient) --- and `external_taint` (not DB-authoritative) are deliberately not --- represented by any table here. - CREATE TABLE IF NOT EXISTS mutation_trace_worktrees ( worktree_id TEXT PRIMARY KEY, cursor_tree TEXT NOT NULL, @@ -38,13 +25,6 @@ ON mutation_trace_scopes (worktree_id); CREATE INDEX IF NOT EXISTS idx_mutation_trace_scopes_worktree_status ON mutation_trace_scopes (worktree_id, status); --- `worktree_id` is deliberately not duplicated here: a processed event's --- identity is exactly `(scope_id, event_id)` (the domain `EventKey`), and --- `scope_id`'s worktree is already a permanent fact owned by --- `mutation_trace_scopes` (`ScopeId -> WorktreeId`, never reassigned). A --- second `worktree_id` column would create two sources of truth for the same --- fact and could disagree with `mutation_trace_scopes` for the same --- `scope_id`; the schema does not represent that inconsistency. CREATE TABLE IF NOT EXISTS mutation_trace_processed_events ( scope_id TEXT NOT NULL, event_id TEXT NOT NULL, diff --git a/cli/src/cli_schema.rs b/cli/src/cli_schema.rs index 93627f5b1..40e86d0d7 100644 --- a/cli/src/cli_schema.rs +++ b/cli/src/cli_schema.rs @@ -122,8 +122,6 @@ pub fn render_help_for_path(path: &[&str]) -> Option { let mut command = Cli::command(); for segment in path { - // Clone required: find_subcommand_mut returns a mutable reference that cannot - // be kept alive across loop iterations, so we must clone to get an owned value command = command.find_subcommand_mut(segment)?.clone(); } @@ -192,11 +190,9 @@ pub enum Commands { #[arg(long, requires = "hooks")] repo: Option, - /// Create the baseline durable-context tree without installing integrations #[arg(long)] bootstrap_context: bool, - /// Install an optional workflow by slug; repeat for several (default: none) #[arg(long = "workflow", value_name = "SLUG")] workflow: Vec, diff --git a/cli/src/services/agent_trace.rs b/cli/src/services/agent_trace.rs index 75223df1a..775ad35db 100644 --- a/cli/src/services/agent_trace.rs +++ b/cli/src/services/agent_trace.rs @@ -250,24 +250,19 @@ pub enum ContributorType { #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub struct Conversation { - /// Absolute lookup URL for the generated top-level agent trace. pub url: String, #[serde(skip_serializing_if = "Option::is_none")] pub contributor: Option, pub ranges: Vec, - /// Optional related resources for this conversation entry. #[serde(skip_serializing_if = "Option::is_none")] pub related: Option>, } -/// A related resource for a conversation entry. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub struct ConversationRelated { - /// Free-form related resource type. #[serde(rename = "type")] pub kind: String, - /// Related resource URL. pub url: String, } @@ -276,7 +271,6 @@ pub struct ConversationRelated { pub struct Contributor { #[serde(rename = "type")] pub kind: ContributorType, - /// Model provenance for this contributor; omitted when unknown. #[serde(skip_serializing_if = "Option::is_none")] pub model_id: Option, } @@ -292,7 +286,6 @@ pub struct LineRange { pub contributor: Option, } -/// A file-level entry in the minimal agent-trace payload. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub struct TraceFile { @@ -300,26 +293,19 @@ pub struct TraceFile { pub conversations: Vec, } -/// Top-level minimal agent-trace payload. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub struct AgentTrace { - /// Agent-trace payload version. #[serde(default = "default_agent_trace_version")] pub version: String, - /// Trace record identifier (`UUIDv7` generated from commit-time metadata). #[serde(default)] pub id: String, - /// RFC 3339 timestamp string sourced from caller-provided commit metadata. #[serde(default)] pub timestamp: String, - /// Version control metadata sourced from caller-provided commit metadata. #[serde(skip_serializing_if = "Option::is_none")] pub vcs: Option, - /// Optional tool metadata sourced from caller-provided metadata input. #[serde(skip_serializing_if = "Option::is_none")] pub tool: Option, - /// Implementation-specific metadata for SCE-generated traces. #[serde(default = "default_agent_trace_metadata")] pub metadata: AgentTraceMetadata, pub files: Vec, diff --git a/cli/src/services/agent_trace/repository_path.rs b/cli/src/services/agent_trace/repository_path.rs index cae097044..b90a30b83 100644 --- a/cli/src/services/agent_trace/repository_path.rs +++ b/cli/src/services/agent_trace/repository_path.rs @@ -38,9 +38,6 @@ impl RepositoryRoot { repository_root } - /// Resolves `path` to its repository identity. Absolute paths stand on - /// their own; a relative path is interpreted only in the coordinate system - /// `origin` establishes, and is rejected when there is none. pub(crate) fn repository_path( &self, path: &str, diff --git a/cli/src/services/agent_trace_db/lifecycle.rs b/cli/src/services/agent_trace_db/lifecycle.rs index b00acce28..2e5318701 100644 --- a/cli/src/services/agent_trace_db/lifecycle.rs +++ b/cli/src/services/agent_trace_db/lifecycle.rs @@ -236,9 +236,6 @@ fn resolve_lifecycle_agent_trace_db_path(repo_root: Option<&Path>) -> Result { pub time_ms: i64, @@ -192,7 +179,6 @@ pub struct ClaudeModelStateObservation { pub observed_at_ms: i64, } -/// Raw diff trace row read from the agent trace database. #[derive(Clone, Debug, Eq, PartialEq)] pub struct DiffTracePatchRow { pub id: i64, @@ -217,19 +203,10 @@ pub struct ParsedDiffTracePatch { pub path_origin: DiffTracePathOrigin, } -/// Coordinate system in which a diff-trace row's file paths are expressed. -/// -/// Absolute paths resolve on their own under every origin; the origin only -/// decides how a relative path is interpreted. An unknown origin fails closed. #[derive(Clone, Debug, Eq, PartialEq)] pub enum DiffTracePathOrigin { - /// Git patch paths: relative paths are repository-relative. RepositoryRelative, - /// Claude structured paths with a recorded absolute `cwd`: relative paths - /// are relative to that working directory. WorkingDirectory(String), - /// Claude structured paths without a usable absolute `cwd`: relative paths - /// have no established coordinate system and cannot be resolved. AbsoluteOnly, } @@ -295,7 +272,6 @@ impl std::fmt::Display for MessageRole { } } -/// Message insert payload for the `messages` table. #[derive(Clone, Debug, Eq, PartialEq)] pub struct InsertMessageInsert { pub session_id: String, @@ -304,7 +280,6 @@ pub struct InsertMessageInsert { pub generated_at_unix_ms: i64, } -/// Part type constraint for the `parts` table. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum PartType { Text, @@ -324,7 +299,6 @@ impl std::fmt::Display for PartType { } } -/// Part insert payload for the `parts` table (append-only, no upsert). #[derive(Clone, Debug, Eq, PartialEq)] pub struct InsertPartInsert { pub part_type: PartType, @@ -509,12 +483,6 @@ async fn insert_parts_with( db.execute(&sql, params).await } -/// Atomically insert one conversation `messages` row and its one `parts` -/// row: if `(message.session_id, message.message_id)` already exists, this -/// is a no-op (`Ok(false)`); otherwise both rows insert together in one -/// transaction (`Ok(true)`). `fail_before_part_insert` is a test-only hook -/// forcing the transaction to fail after the message insert and before the -/// part insert, to prove both roll back together. async fn insert_conversation_text_event_with( db: &mut TursoDb, message: InsertMessageInsert, diff --git a/cli/src/services/agent_trace_db/repository.rs b/cli/src/services/agent_trace_db/repository.rs index e9f29d506..a19e3d48b 100644 --- a/cli/src/services/agent_trace_db/repository.rs +++ b/cli/src/services/agent_trace_db/repository.rs @@ -34,44 +34,23 @@ const REQUIRED_REPOSITORY_SCHEMA_TABLES: &[&str] = &[ "parts", ]; -/// Seeds the single metadata row on first initialization; concurrent first -/// opens race safely because the conflicting insert is ignored and the stored -/// value is validated afterwards. const INSERT_REPOSITORY_METADATA_SQL: &str = "INSERT INTO repository_metadata (id, repository_id) VALUES (1, ?1) ON CONFLICT (id) DO NOTHING"; -/// Atomically claims `source_instance_id` for the single metadata row: it -/// only ever replaces an empty placeholder, so a losing racer's candidate is -/// silently discarded (the `UPDATE` affects zero rows) and an already-valid -/// stored value is never overwritten. const CLAIM_SOURCE_INSTANCE_ID_SQL: &str = "UPDATE repository_metadata SET source_instance_id = ?1 WHERE id = 1 AND source_instance_id = ''"; -/// Physical database identity for one repository-scoped Agent Trace DB, -/// alongside the existing logical repository identity. -/// -/// `repository_id` identifies the logical Git repository this database is -/// scoped to. `source_instance_id` identifies this one physical database -/// file's lineage: it is generated once per physical database, independent -/// of `repository_id`, remote URL, checkout ID, filesystem path, hostname, or -/// user/workspace identity, and stays stable across reopen and repeated -/// `sce setup` runs. #[derive(Debug, Clone, PartialEq, Eq)] pub struct RepositoryMetadata { pub repository_id: String, pub source_instance_id: String, } -/// Generate a new candidate source-instance identity. -/// -/// Callers must not assume the result is UUID-shaped; `is_valid_source_instance_id` -/// only requires a non-empty (once trimmed) value. pub fn generate_source_instance_id() -> String { Uuid::new_v4().to_string() } -/// Whether a stored or candidate value is a usable source-instance identity. pub fn is_valid_source_instance_id(value: &str) -> bool { !value.trim().is_empty() } @@ -133,7 +112,6 @@ impl std::fmt::Display for ExistingRepositoryDbError { impl std::error::Error for ExistingRepositoryDbError {} -/// Repository-scoped Agent Trace database configuration. pub struct RepositoryAgentTraceDbSpec; impl DbSpec for RepositoryAgentTraceDbSpec { @@ -155,13 +133,9 @@ impl DbSpec for RepositoryAgentTraceDbSpec { const KIND: DatabaseKind = DatabaseKind::AgentTrace; } -/// Repository-scoped Agent Trace Turso database adapter. pub type RepositoryAgentTraceDb = TursoDb; impl RepositoryAgentTraceDb { - /// Open a repository-scoped Agent Trace database at an explicit path without - /// running migrations, for read-only hook/runtime paths that must not - /// migrate from a high-frequency caller. pub async fn open_for_hooks_without_migrations_at( path: impl AsRef, ) -> Result { @@ -267,17 +241,11 @@ impl RepositoryAgentTraceDb { }) } - /// Verify that the repository-scoped schema baseline already exists. pub async fn ensure_schema_ready_for_hooks(&self) -> Result<()> { self.ensure_schema_ready(REPOSITORY_AGENT_TRACE_SCHEMA_SETUP_GUIDANCE) .await } - /// Repair the narrow concurrent-initialization case where the one-file - /// schema batch completed but recording `__sce_migrations` raced with - /// another first opener. This never creates trace tables; it only records - /// the baseline migration after all required repository tables already - /// exist. pub async fn repair_missing_repository_schema_migration_metadata(&self) -> Result<()> { for table in REQUIRED_REPOSITORY_SCHEMA_TABLES { if !self.sqlite_object_exists("table", table).await? { @@ -302,17 +270,6 @@ impl RepositoryAgentTraceDb { Ok(!rows.is_empty()) } - /// Seed repository metadata on first initialization, atomically claim a - /// `source_instance_id` for this physical database if none is set yet, - /// and validate the result on every open. - /// - /// The stored `repository_id` must match the resolved repository ID for - /// this database path; a mismatch means the file does not belong to the - /// resolved repository and is an error rather than a write target. - /// `source_instance_id` is claimed with a concurrency-safe `UPDATE ... - /// WHERE source_instance_id = ''`: concurrent first opens generate their - /// own candidate, but only one claim can affect the row, so every caller - /// re-reads the row afterward and returns whichever value actually won. pub async fn verify_or_initialize_repository_metadata( &self, repository_id: &str, @@ -383,14 +340,10 @@ impl RepositoryAgentTraceDb { Ok(rows.into_iter().next()) } - /// Insert a diff trace payload into the repository-scoped `diff_traces` - /// table. Rows remain repository-level; no checkout provenance is stored. pub async fn insert_diff_trace(&self, input: DiffTraceInsert<'_>) -> Result { insert_diff_trace_with(self, input).await } - /// Insert a post-commit patch intersection into the repository-scoped - /// `post_commit_patch_intersections` table. pub async fn insert_post_commit_patch_intersection( &self, input: PostCommitPatchIntersectionInsert<'_>, @@ -417,9 +370,6 @@ impl RepositoryAgentTraceDb { super::claude_model_state_by_session_and_agent_with(self, session_id, agent_id).await } - /// Query and parse recent diff trace patches within the inclusive time - /// window for this repository-scoped database. Rows remain repository-level; - /// no checkout filter or checkout provenance is applied. pub async fn recent_diff_trace_patches( &self, cutoff_time_ms: i64, @@ -436,24 +386,14 @@ impl RepositoryAgentTraceDb { diff_trace_patches_before_commit_with(self, lower_time_ms, cutoff).await } - /// Insert message rows with one multi-row statement, ignoring duplicate - /// `(session_id, message_id)` rows. pub async fn insert_messages(&self, inputs: Vec) -> Result { insert_messages_with(self, inputs).await } - /// Append part rows with one multi-row statement. pub async fn insert_parts(&self, inputs: Vec) -> Result { insert_parts_with(self, inputs).await } - /// Atomically insert one conversation `messages` row and its one - /// `parts` row: if `(message.session_id, message.message_id)` already - /// exists, this is a no-op (`Ok(false)`); otherwise both rows insert - /// together in one transaction (`Ok(true)`). Used by conversation - /// text-event handlers (e.g. Codex `UserPromptSubmit`/`Stop`) in place - /// of separate `insert_messages`/`insert_parts` calls, so a replayed or - /// concurrent duplicate delivery never produces an orphaned `parts` row. pub async fn insert_conversation_text_event( &mut self, message: InsertMessageInsert, diff --git a/cli/src/services/agent_trace_export/mod.rs b/cli/src/services/agent_trace_export/mod.rs index 6b2af6e9a..d009fbc44 100644 --- a/cli/src/services/agent_trace_export/mod.rs +++ b/cli/src/services/agent_trace_export/mod.rs @@ -1,22 +1,12 @@ -//! Read-only incremental export readers for the Agent Trace capture streams. -//! -//! This module establishes the local read/export boundary: cursor in, owned -//! wire-compatible rows out. It performs no database mutation, holds no local -//! sync cursor, and makes no network calls. - use anyhow::{bail, Context, Result}; use serde::Serialize; use crate::services::agent_trace_db::{repository::RepositoryAgentTraceDb, MessageRole}; -/// Maximum number of rows a single export reader call may return. pub const AGENT_TRACE_EXPORT_BATCH_SIZE: usize = 100; -/// Largest integer value that round-trips exactly through an IEEE-754 double -/// (`Number.MAX_SAFE_INTEGER`). pub const JS_MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991; -/// Rejects a negative cursor. pub fn validate_cursor(cursor: i64) -> Result<()> { if cursor < 0 { bail!("agent trace export cursor must be >= 0, got {cursor}"); @@ -25,7 +15,6 @@ pub fn validate_cursor(cursor: i64) -> Result<()> { Ok(()) } -/// Rejects a zero limit or a limit above [`AGENT_TRACE_EXPORT_BATCH_SIZE`]. pub fn validate_limit(limit: usize) -> Result<()> { if limit == 0 { bail!("agent trace export limit must be greater than 0"); @@ -40,9 +29,6 @@ pub fn validate_limit(limit: usize) -> Result<()> { Ok(()) } -/// Rejects a value outside `0..=JS_MAX_SAFE_INTEGER`, the range an exportable -/// numeric field must stay within to survive JSON round-trip without -/// truncation or casting. pub fn validate_js_safe_integer(value: i64) -> Result<()> { if !(0..=JS_MAX_SAFE_INTEGER).contains(&value) { bail!("agent trace export value {value} is outside the JS-safe-integer range 0..={JS_MAX_SAFE_INTEGER}"); @@ -254,9 +240,6 @@ fn message_role_from_column(value: &str) -> Result { } } -/// Converts a validated `limit` (already bounded by [`validate_limit`] to -/// `1..=AGENT_TRACE_EXPORT_BATCH_SIZE`) into the `i64` the SQL `LIMIT` -/// parameter requires. fn limit_as_i64(limit: usize) -> i64 { i64::try_from(limit).expect("validated limit should fit in i64") } diff --git a/cli/src/services/agent_trace_storage/mod.rs b/cli/src/services/agent_trace_storage/mod.rs index 23865d76b..02b99c673 100644 --- a/cli/src/services/agent_trace_storage/mod.rs +++ b/cli/src/services/agent_trace_storage/mod.rs @@ -14,39 +14,20 @@ use crate::services::repository_identity::resolve::{ const REPOSITORY_DB_INITIALIZATION_ATTEMPTS: usize = 20; const REPOSITORY_DB_INITIALIZATION_RETRY_DELAY: Duration = Duration::from_millis(100); -/// Inputs needed to resolve the active repository-scoped Agent Trace storage. -/// -/// The identity inputs mirror the `agent_trace.repository_id` and -/// `agent_trace.repository_remote` configuration keys; callers pass the -/// already-resolved configuration values. #[derive(Clone, Copy, Debug)] pub struct AgentTraceStorageContext<'a> { - /// Root of the Git working tree the current command runs in. pub repository_root: &'a Path, - /// Explicit `agent_trace.repository_id` configuration value, if set. pub explicit_repository_id: Option<&'a str>, - /// Configured `agent_trace.repository_remote` name (default `origin`). pub repository_remote: &'a str, } -/// The resolved active Agent Trace storage for one repository checkout. pub struct ResolvedAgentTraceStorage { - /// Repository identity (canonical identity plus repository ID) and the - /// source it was resolved from. pub repository_identity: ResolvedRepositoryIdentity, - /// Repository-scoped database path - /// `/sce/repos//agent-trace.db`. pub db_path: PathBuf, - /// Open repository-scoped Agent Trace database. pub db: RepositoryAgentTraceDb, - /// Physical database identity (`repository_id`/`source_instance_id`) - /// produced by the same verification/initialization call that opened - /// `db`. pub metadata: RepositoryMetadata, } -/// Resolves the repository-scoped Agent Trace storage for a checkout using -/// the canonical state root from the default-path catalog. pub async fn resolve_agent_trace_storage( context: &AgentTraceStorageContext<'_>, ) -> Result { @@ -55,14 +36,6 @@ pub async fn resolve_agent_trace_storage( open_storage(repository_identity, db_path).await } -/// Resolves repository-scoped Agent Trace storage for high-frequency hook -/// runtime callers using the canonical state root. -/// -/// Never runs migrations, including migration `002`: the database must -/// already have been brought up to date by `sce setup`. A missing or -/// baseline-only (pre-`002`) database fails with the same `sce setup` -/// guidance `ensure_schema_ready_for_hooks` already reports, rather than -/// silently migrating it from a hook path. pub async fn resolve_agent_trace_storage_for_hook_runtime( context: &AgentTraceStorageContext<'_>, ) -> Result { @@ -71,8 +44,6 @@ pub async fn resolve_agent_trace_storage_for_hook_runtime( open_storage_for_hook_runtime(repository_identity, db_path).await } -/// Hook-runtime resolution core against an explicit state root, so tests can -/// exercise the full path without touching the real user state directory. pub async fn resolve_agent_trace_storage_for_hook_runtime_at_state_root( context: &AgentTraceStorageContext<'_>, state_root: &Path, diff --git a/cli/src/services/agent_trace_sync/mod.rs b/cli/src/services/agent_trace_sync/mod.rs index c10f607fd..92b98b1c7 100644 --- a/cli/src/services/agent_trace_sync/mod.rs +++ b/cli/src/services/agent_trace_sync/mod.rs @@ -40,22 +40,12 @@ pub enum BatchAttemptOutcome { Terminal(ControlPlaneError), } -/// Terminal failure of [`sync_stream`]. #[derive(Debug)] pub enum StreamSyncError { - /// The local-row reader closure failed. Read(String), - /// The `/state`-refresh closure failed. Refresh(ControlPlaneError), - /// A syntactically successful batch response did not match the rows - /// that were sent (`accepted != rows.len()` or - /// `cursor != rows.last().source_row_id()`). InvalidResponse(String), - /// The batch failed with a terminal control-plane error. Unlike - /// [`Self::Refresh`], this does not represent a failed `/state` call. Terminal(ControlPlaneError), - /// The reconciliation loop exceeded [`RECONCILIATION_MAX_ATTEMPTS`] - /// without converging. DidNotConverge, } @@ -79,10 +69,6 @@ impl fmt::Display for StreamSyncError { impl std::error::Error for StreamSyncError {} impl StreamSyncError { - /// True only when the underlying `ControlPlaneError` (from a `Refresh` - /// or `Terminal` failure) means the caller has no usable credentials. - /// `Read`, `InvalidResponse`, and `DidNotConverge` never carry a - /// `ControlPlaneError` and are never authentication failures. pub fn is_authentication_failure(&self) -> bool { match self { Self::Refresh(error) | Self::Terminal(error) => error.is_authentication_failure(), @@ -90,10 +76,6 @@ impl StreamSyncError { } } - /// True only when the underlying `ControlPlaneError` (from a `Refresh` - /// or `Terminal` failure) means local credential storage is unavailable. - /// `Read`, `InvalidResponse`, and `DidNotConverge` never carry a - /// `ControlPlaneError` and are never storage failures. pub fn storage_failure(&self) -> Option { match self { Self::Refresh(error) | Self::Terminal(error) => error.storage_failure(), @@ -102,7 +84,6 @@ impl StreamSyncError { } } -/// Outcome of a fully converged [`sync_stream`] run for one stream. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct StreamSyncOutcome { pub uploaded: usize, @@ -111,18 +92,6 @@ pub struct StreamSyncOutcome { pub batches: usize, } -/// Synchronizes one Agent Trace capture stream: reads local rows after -/// `cursor` via `read_after`, uploads them in batches bounded by -/// `batch_limit` via `ingest_batch`, and advances the cursor only from a -/// validated server response. Never infers the next cursor from -/// `cursor + rows.len()`; it always uses the server-reported `cursor` -/// (or, on reconciliation, the freshly fetched `/state` cursor). -/// -/// On `Conflict` or `Ambiguous`, calls `refresh_cursor` and resumes from the -/// refreshed value: if it advanced, the next read naturally skips the -/// already-accepted rows; if unchanged, the same rows are re-read and -/// resent. Both cases share one bounded reconciliation counter. A `Terminal` -/// outcome stops immediately without calling `refresh_cursor`. pub async fn sync_stream<'a, T, ReadFn, IngestFn, RefreshFn>( initial_cursor: i64, batch_limit: usize, diff --git a/cli/src/services/auth.rs b/cli/src/services/auth.rs index 3e89f8e84..081128642 100644 --- a/cli/src/services/auth.rs +++ b/cli/src/services/auth.rs @@ -137,8 +137,6 @@ impl From for AuthError { } } -/// HTTP-only device auth completion: polls for the device token and returns -/// the raw `TokenResponse` without calling `save_tokens`. pub(crate) async fn complete_device_auth_flow_returning_token( client: &reqwest::Client, api_base_url: &str, @@ -153,9 +151,6 @@ pub(crate) async fn complete_device_auth_flow_returning_token( Ok(token) } -/// HTTP-only token validation: checks an existing stored token for expiry and -/// refreshes if needed. Does NOT call any `token_storage` functions. -/// Returns the raw `TokenResponse` (re-using the stored token if not expired). pub(crate) async fn ensure_valid_token_returning_token( client: &reqwest::Client, api_base_url: &str, @@ -182,9 +177,6 @@ pub(crate) async fn ensure_valid_token_returning_token( .map_err(map_refresh_failure_for_public_cli) } -/// HTTP-only token renewal: accepts a refresh token directly and calls the -/// private `refresh_access_token`. Does NOT call any `token_storage` functions. -/// Returns the raw `TokenResponse`. pub(crate) async fn renew_stored_token_from_refresh_token( client: &reqwest::Client, api_base_url: &str, diff --git a/cli/src/services/auth_db/mod.rs b/cli/src/services/auth_db/mod.rs index 5e2934bb0..353e55618 100644 --- a/cli/src/services/auth_db/mod.rs +++ b/cli/src/services/auth_db/mod.rs @@ -1,5 +1,3 @@ -//! Encrypted auth Turso database adapter. - use std::path::PathBuf; use anyhow::Result; @@ -12,7 +10,6 @@ use crate::{ }, }; -/// Encrypted auth database configuration. pub struct AuthDbSpec; impl DbSpec for AuthDbSpec { @@ -31,7 +28,6 @@ impl DbSpec for AuthDbSpec { const KIND: DatabaseKind = DatabaseKind::Auth; } -/// Encrypted auth Turso database adapter. pub type AuthDb = EncryptedTursoDb; pub mod lifecycle; diff --git a/cli/src/services/bash_policy.rs b/cli/src/services/bash_policy.rs index c4a53b88d..389b334f1 100644 --- a/cli/src/services/bash_policy.rs +++ b/cli/src/services/bash_policy.rs @@ -44,17 +44,11 @@ pub(crate) struct PolicyMatch { pub(crate) id: String, pub(crate) message: String, pub(crate) argv_prefix: Vec, - /// Wrapper argv prefixes that already satisfy this policy. A policy does not - /// fire when the matched command was unwrapped from one of these wrappers, - /// so `use-nix-for-rg` with `[["nix"]]` stays quiet for - /// `nix shell nixpkgs#ripgrep -c rg ...` while still blocking a bare `rg`. pub(crate) satisfied_by: Vec>, pub(crate) source: PolicySource, pub(crate) order: usize, } -/// A command segment reduced to the argv a policy matches against, together with -/// the argv of each wrapper it was unwrapped from (outermost first). #[derive(Clone, Debug, Eq, PartialEq)] struct NormalizedSegment { argv: Vec, @@ -934,8 +928,6 @@ mod tests { ); } - // --- Malformed custom policy tests (TS parity) --- - #[test] fn bash_policy_ignores_custom_policy_with_empty_id() { let config = config( @@ -1026,8 +1018,6 @@ mod tests { )); } - // --- parseCommandSegments edge cases (TS parity) --- - #[test] fn parse_command_segments_returns_none_for_empty_string() { assert_eq!(parse_command_segments(""), None); @@ -1108,8 +1098,6 @@ mod tests { ); } - // --- Shell operator policy tests (TS parity) --- - #[test] fn bash_policy_blocks_or_or_operator_segment() { let config = config(&["forbid-git-all"], Vec::new()); diff --git a/cli/src/services/codex_hook_config.rs b/cli/src/services/codex_hook_config.rs index e2c36d81f..6a5b9b302 100644 --- a/cli/src/services/codex_hook_config.rs +++ b/cli/src/services/codex_hook_config.rs @@ -1,10 +1,3 @@ -//! Shared structural ownership and merge logic for Codex's repository hook config. -//! -//! The accepted shape intentionally mirrors the relevant current upstream -//! `HooksFile`, `HookEventsToml`, `MatcherGroup`, and `HookHandlerConfig` JSON -//! deserialization rules. This keeps setup and doctor aligned without taking a -//! dependency on Codex's source or preserving JSON that Codex cannot load. - use anyhow::{bail, Context, Result}; use serde::Deserialize; use serde_json::{Map, Value}; @@ -80,11 +73,6 @@ pub(crate) fn hook_event_key_label(event: &str) -> &'static str { } } -/// Merge the canonical generated Codex hooks into an existing file. -/// -/// A missing file is installed verbatim. An existing file is parsed and -/// structurally validated before any merged bytes are returned, allowing the -/// caller to preserve it unchanged when parsing or validation fails. pub(crate) fn merge_or_create( existing_bytes: Option<&[u8]>, generated_bytes: &[u8], @@ -120,27 +108,13 @@ struct Registration { handler: Value, } -/// The structural state of one required Codex hook registration, independent -/// of Codex's own separate hook-trust bookkeeping (see `codex_hook_trust`). #[derive(Clone, Debug, Eq, PartialEq)] pub(crate) enum RegistrationStructuralState { - /// Exactly one SCE-owned handler exists anywhere for this event, it sits - /// in the registration's canonical matcher group, and it matches the - /// canonical generated handler byte-for-byte. PresentAndCurrent, - /// No SCE-owned handler exists in any matcher group for this event. Missing, - /// An SCE-owned handler exists somewhere for this event, but the - /// registration is not `PresentAndCurrent`: more than one owned handler - /// (whether duplicated within one group or spread across groups), one - /// sitting in the wrong matcher group, or one whose content does not - /// match the canonical generated handler. Stale, } -/// One required Codex hook registration's structural diagnosis, carrying the -/// existing owned handler JSON (when present) so callers can compute Codex's -/// own trust hash for it without re-parsing the document. #[derive(Clone, Debug, Eq, PartialEq)] pub(crate) struct RegistrationDiagnosis { pub(crate) command: CodexHookCommand, @@ -148,17 +122,9 @@ pub(crate) struct RegistrationDiagnosis { pub(crate) matcher: Option<&'static str>, pub(crate) state: RegistrationStructuralState, pub(crate) owned_handler: Option, - /// Position of the matching matcher group among `hooks.`, and of - /// the owned handler within that group's `hooks` array, exactly as - /// upstream's `hook_key` enumerates them. `None` when no owned handler - /// was found (state is `Missing`), since there is nothing to key. pub(crate) position: Option<(usize, usize)>, } -/// Whole-document diagnosis backing `sce doctor`'s Codex hook-registration -/// reporting. `Malformed` covers both unparsable JSON and JSON that fails -/// Codex's own structural schema; either way no per-registration state can be -/// determined and the document cannot be safely merged. #[derive(Clone, Debug, Eq, PartialEq)] pub(crate) enum HooksDocumentDiagnosis { Absent, @@ -166,9 +132,6 @@ pub(crate) enum HooksDocumentDiagnosis { Registrations(Vec), } -/// Diagnose each required registration's structural state without writing -/// anything. Mirrors `merge_or_create`'s validation rules exactly so a -/// `PresentAndCurrent` result here always implies a no-op merge. pub(crate) fn diagnose_document( existing_bytes: Option<&[u8]>, generated_bytes: &[u8], @@ -214,13 +177,6 @@ struct OwnedHandlerSighting { in_canonical_group: bool, } -/// Diagnose one required registration by scanning **every** matcher group -/// under `hooks.`, not just the first one whose matcher matches. -/// Setup's merge (`merge_event_groups`) strips SCE-owned handlers from every -/// group for the event, so a duplicate or misplaced SCE handler sitting in a -/// second group is exactly as stale as one in the first; scoping discovery -/// to only the first matching group would let such a document read -/// `PresentAndCurrent` even though `merge_or_create` would still rewrite it. fn diagnose_registration( hooks: &Map, registration: &Registration, diff --git a/cli/src/services/codex_hook_policy.rs b/cli/src/services/codex_hook_policy.rs index b595bc3d5..f220a2bb4 100644 --- a/cli/src/services/codex_hook_policy.rs +++ b/cli/src/services/codex_hook_policy.rs @@ -1,51 +1,3 @@ -//! Effective Codex hook-discovery *policy* readiness for SCE's project-owned -//! `.codex/hooks.json` registrations, obtained by asking the installed Codex -//! binary for its own composed effective configuration requirements rather -//! than reproducing Codex's multi-layer requirements composition in SCE. -//! -//! This is deliberately a separate dimension from `codex_hook_trust`: policy -//! answers "will Codex consider this hook *source* eligible at all?", while -//! trust answers "given an eligible source, has this handler been enabled and -//! durably trusted?". A registration is only executable when both are -//! satisfied. -//! -//! Upstream reference (`openai/codex` commit -//! `a8468330bb5f45e9f4d2ec630b01ea8c52908be3`): -//! - `hooks/src/engine/discovery.rs` `HookDiscoveryPolicy::allows`: -//! `!allow_managed_hooks_only || source.is_managed`, applied per config -//! layer before that layer's `hooks.json`/TOML hooks are even loaded. -//! Project `.codex/hooks.json` hooks are `HookSource::Project`, -//! `is_managed = false` (`hook_metadata_for_config_layer_source`), so they -//! are entirely excluded from discovery when the policy is active, -//! regardless of structural or trust state. -//! - `config/src/config_requirements.rs` `ConfigRequirements::allow_managed_hooks_only` -//! (`Option`) is populated only from `requirements.toml`/managed -//! layers; `docs/config.md` documents that putting it in `config.toml` does -//! not enable the policy, confirmed by -//! `hooks/src/engine/mod_tests.rs::allow_managed_hooks_only_in_config_toml_does_not_enable_policy`. -//! - Requirements are composed from multiple sources -//! (`config/src/config_requirements.rs` `RequirementSource`: system -//! `requirements.toml`, legacy managed `config.toml`/MDM, MDM managed -//! preferences, backend-delivered enterprise-managed layers, and composites -//! of these), so SCE cannot safely re-derive the effective value by reading -//! any single file; it must ask the installed Codex binary for its own -//! composed answer. -//! - `codex app-server` exposes that composed answer read-only via the -//! `configRequirements/read` method -//! (`app-server-protocol/src/protocol/common.rs` -//! `ConfigRequirementsRead => "configRequirements/read"`, no params), -//! returning `v2::ConfigRequirementsReadResponse { requirements: Option }` -//! (`app-server-protocol/src/protocol/v2/config.rs`), where -//! `ConfigRequirements::allow_managed_hooks_only: Option` serializes -//! as camelCase `allowManagedHooksOnly`. `requirements` itself is `null` -//! when no requirements are configured at all. -//! - Transport: `codex app-server --stdio` speaks newline-delimited JSON-RPC -//! 2.0 with the `"jsonrpc"` field omitted (`app-server/README.md` -//! "Protocol"). A connection must send `initialize` -//! (`app-server-protocol/src/protocol/v1.rs` `InitializeParams`/`ClientInfo`) -//! and then an `initialized` notification before any other request is -//! accepted ("Lifecycle Overview"/"Initialization"). - use std::io::{BufRead, BufReader, Write}; use std::process::{Child, ChildStdin, Command, Stdio}; use std::sync::mpsc::{self, RecvTimeoutError}; @@ -53,45 +5,21 @@ use std::time::{Duration, Instant}; use serde_json::{json, Value}; -/// Effective Codex hook-discovery policy readiness for SCE's project-owned -/// `.codex/hooks.json` registrations. Independent of `codex_hook_trust`'s -/// per-handler enabled/trust bookkeeping. #[derive(Clone, Debug, Eq, PartialEq)] pub(crate) enum CodexHookPolicyReadiness { - /// Effective `allow_managed_hooks_only` is absent, `false`, or no - /// requirements are configured at all: Codex's discovery policy does not - /// exclude project `.codex/hooks.json` handlers. ProjectHooksAllowed, - /// Effective `allow_managed_hooks_only = true`: Codex's discovery policy - /// discards every non-managed hook source, including SCE's project - /// `.codex/hooks.json` registrations, regardless of their structural or - /// trust state. PolicyBlocked, - /// The effective policy could not be determined (no Codex executable, - /// spawn/initialization failure, malformed response, timeout, etc.); - /// carries a human-readable reason. Doctor must never treat this the same - /// as `ProjectHooksAllowed`. Unknown(String), } -/// Default command used to probe Codex's effective policy in production: -/// `codex app-server --stdio`, invoked directly (no shell). const DEFAULT_CODEX_COMMAND: &str = "codex"; -/// Upper bound on the whole probe's wall-clock lifetime (spawn, initialize, -/// `configRequirements/read`, and teardown). `sce doctor` must never hang -/// because Codex is broken, slow, or unavailable. pub(crate) const DEFAULT_POLICY_PROBE_TIMEOUT: Duration = Duration::from_secs(5); -/// Production entry point: probe the installed `codex` binary on `PATH`. pub(crate) fn probe_default() -> CodexHookPolicyReadiness { probe_effective_policy(DEFAULT_CODEX_COMMAND.as_ref(), DEFAULT_POLICY_PROBE_TIMEOUT) } -/// Probe one Codex executable's effective hook-discovery policy over -/// `codex app-server --stdio`, bounded by `timeout`. Never panics on -/// malformed output; always terminates and reaps the child process before -/// returning, on every exit path (success, protocol error, or timeout). pub(crate) fn probe_effective_policy( codex_command: &std::ffi::OsStr, timeout: Duration, @@ -158,11 +86,6 @@ pub(crate) fn probe_effective_policy( readiness } -/// Drives the initialize/initialized/`configRequirements/read` exchange over -/// an already-spawned child's stdin/stdout channel. Split out from -/// `probe_effective_policy` so the child-process teardown in the caller is -/// unconditional (this function only ever returns a readiness value, never -/// panics or leaks the process). fn run_policy_probe_session( stdin: &mut ChildStdin, rx: &mpsc::Receiver, @@ -227,8 +150,6 @@ fn terminate_and_reap_with_unknown(child: Child, reason: String) -> CodexHookPol CodexHookPolicyReadiness::Unknown(reason) } -/// Ensures the probed Codex process is always terminated and reaped, -/// regardless of which path through `probe_effective_policy` returns. struct ChildGuard(Child); impl ChildGuard { @@ -256,10 +177,6 @@ enum ResponseOutcome { Error(String), } -/// Reads JSONL lines from `rx` until one whose `id` matches `expected_id` is -/// found, skipping unrelated notifications/responses (bounded, so a chatty or -/// malicious process cannot spin this loop forever), or until `deadline` -/// elapses. fn read_response_for_id( rx: &mpsc::Receiver, expected_id: i64, @@ -323,9 +240,6 @@ fn read_response_for_id( } } -/// Parses a `configRequirements/read` response's `result` value into policy -/// readiness. Pure and independent of process I/O so it can be tested with -/// captured fixtures. fn parse_config_requirements_result(result: &Value) -> CodexHookPolicyReadiness { let Some(requirements) = result.get("requirements") else { return CodexHookPolicyReadiness::Unknown( @@ -356,8 +270,6 @@ fn parse_config_requirements_result(result: &Value) -> CodexHookPolicyReadiness mod tests { use super::*; - // -- parse_config_requirements_result: pure-parser fixtures -------------- - #[test] fn null_requirements_allows_project_hooks() { let result = json!({ "requirements": null }); @@ -430,20 +342,10 @@ mod tests { )); } - // -- probe_effective_policy: real subprocess spawn, using fake `codex` -- - // scripts (executed directly, never through `sh -c`/`bash -c`/`eval`) so - // these tests never depend on a real installed Codex binary. - #[cfg(unix)] fn temp_script(name: &str, contents: &str) -> std::path::PathBuf { use std::os::unix::fs::PermissionsExt; use std::sync::atomic::{AtomicU64, Ordering}; - // A coarse-resolution clock in some sandboxes can make - // `SystemTime::now()` collide across concurrently-running test - // threads that write to the same OS temp directory; an atomic - // counter guarantees uniqueness regardless of clock resolution - // (`Command::spawn` on a path another thread's child process is - // still executing otherwise fails with `ETXTBSY`). static COUNTER: AtomicU64 = AtomicU64::new(0); let nonce = COUNTER.fetch_add(1, Ordering::Relaxed); let path = std::env::temp_dir().join(format!( @@ -459,13 +361,6 @@ mod tests { path } - /// Some sandboxed/overlay filesystems spuriously return `ETXTBSY` - /// ("Text file busy") when `exec`ing a script that was written and - /// `chmod`ed moments earlier by a concurrently-running test thread, even - /// with a guaranteed-unique path. Retrying a couple of times is the - /// standard mitigation for this known transient OS race and keeps these - /// tests meaningful (they still fail on a genuine, persistent spawn - /// failure). #[cfg(unix)] fn probe_effective_policy_retrying_on_transient_busy_text( codex_command: &std::ffi::OsStr, diff --git a/cli/src/services/codex_hook_trust.rs b/cli/src/services/codex_hook_trust.rs index 9153bc3d5..b0358e0eb 100644 --- a/cli/src/services/codex_hook_trust.rs +++ b/cli/src/services/codex_hook_trust.rs @@ -1,58 +1,14 @@ -//! Read-only diagnosis of Codex's own per-handler hook-*trust* bookkeeping -//! (enabled / `trusted_hash`) for SCE-owned `.codex/hooks.json` -//! registrations. -//! -//! This is deliberately only one of two independent dimensions Codex -//! requires before it will actually execute a project hook handler. This -//! module answers "given an eligible hook *source*, has this handler been -//! enabled and durably trusted?" — it says nothing about whether Codex -//! considers the *source* (SCE's project `.codex/hooks.json`) eligible at -//! all. That second dimension is effective hook-discovery *policy* -//! (`allow_managed_hooks_only`), owned entirely by `codex_hook_policy`. A -//! project registration is only executable when both are satisfied: -//! structurally current, policy-eligible, *and* trusted. See -//! `codex_hook_policy`'s module documentation for why policy cannot be -//! determined by reading any file this module could read, and for the -//! upstream discovery-policy source references. -//! -//! Mirrors current upstream `openai/codex` (commit -//! `8e649e3afa5cdddfb09a1b85a090b94775045d9b`): -//! `hooks/src/engine/discovery.rs` (`hook_hash`, `hook_trust_status`, -//! `hook_enabled`, `hook_trusted_hash`, `NormalizedHookIdentity`), -//! `config/src/fingerprint.rs` (`version_for_toml`), and `hooks/src/lib.rs` -//! (`hook_key`, `hook_event_key_label`). SCE never writes this state; see -//! `codex_hook_config` for the SCE-owned merge/diagnosis boundary this module -//! deliberately stays out of (no auto-trust, no state.toml writes). -//! -//! Scope limitation: Codex's effective hook state is layered from its user -//! config (`$CODEX_HOME/config.toml`) and ephemeral, process-local session -//! flags (`hooks/src/config_rules.rs` `hook_states_from_stack`). Doctor is a -//! static, out-of-process inspection, so it can only ever read the durable -//! user-config layer; a live Codex session with session-flag overrides can -//! diverge from what doctor reports here. - use std::path::{Path, PathBuf}; use serde::Deserialize; use serde_json::Value; use sha2::{Digest, Sha256}; -/// Default output-context token budget Codex applies when -/// `additionalContextLimit` is unset (`hooks/src/output_spill.rs` -/// `DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT`). An explicit value equal to this -/// default is normalized away before hashing, exactly as upstream does. const DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT: u64 = 2_500; -/// Codex gives `SessionEnd` and `Interrupt` command hooks a one-second -/// default timeout and clamps them to three seconds before hashing their -/// normalized identity (`hooks/src/engine/discovery.rs`). const DEFAULT_LIFECYCLE_HOOK_TIMEOUT: u64 = 1; const MAX_LIFECYCLE_HOOK_TIMEOUT: u64 = 3; -/// Events whose hooks may carry `additionalContext` -/// (`hooks/src/engine/discovery.rs`); `Stop` cannot, so an -/// `additionalContextLimit` set on a Stop handler is dropped before hashing, -/// matching upstream's own normalization. const EVENTS_SUPPORTING_ADDITIONAL_CONTEXT: [&str; 4] = [ "UserPromptSubmit", "PreToolUse", @@ -60,40 +16,20 @@ const EVENTS_SUPPORTING_ADDITIONAL_CONTEXT: [&str; 4] = [ "SessionStart", ]; -/// Effective trust readiness for one Codex hook registration's current -/// on-disk handler. `Managed` never applies here: SCE only ever registers -/// project-owned (non-managed) handlers in `.codex/hooks.json`. #[derive(Clone, Debug, Eq, PartialEq)] pub(crate) enum TrustReadiness { - /// Enabled and `trusted_hash` matches the handler's current hash: this - /// handler is durably trusted. This alone does **not** mean Codex will - /// execute it — `Trusted` says nothing about whether Codex's - /// hook-discovery policy considers this project handler's *source* - /// eligible at all (see `codex_hook_policy`). The accurate reading is - /// "the current non-managed handler is enabled and durably trusted, - /// assuming Codex policy permits this hook source." Trusted, - /// Enabled but no `trusted_hash` is recorded for this handler yet. Untrusted, - /// Enabled but the recorded `trusted_hash` does not match the handler's - /// current hash (the handler content changed since it was trusted). Modified, - /// The user's Codex config explicitly disabled this handler - /// (`hooks.state."".enabled = false`). Disabled, - /// Trust state could not be determined; carries a human-readable reason. Unknown(String), } -/// Where doctor reads Codex's durable, user-scoped hook-trust state from. -/// Injectable so tests never touch the real `$CODEX_HOME`. #[derive(Clone, Debug, Eq, PartialEq)] pub(crate) struct TrustContext { pub(crate) codex_home: Option, } -/// Resolve `$CODEX_HOME`, falling back to `~/.codex` (Codex's own default; -/// see `openai/codex` `config/src/loader/local.rs`). pub(crate) fn default_trust_context() -> TrustContext { let codex_home = std::env::var_os("CODEX_HOME") .map(PathBuf::from) @@ -101,11 +37,6 @@ pub(crate) fn default_trust_context() -> TrustContext { TrustContext { codex_home } } -/// Diagnose whether Codex will actually execute the given SCE-owned handler -/// for one required registration. `hooks_json_path` must be the on-disk path -/// to the `.codex/hooks.json` file the handler was read from, and `position` -/// the `(group_index, handler_index)` it occupies there (from -/// `codex_hook_config::RegistrationDiagnosis::position`). pub(crate) fn trust_readiness( context: &TrustContext, hooks_json_path: &Path, @@ -148,12 +79,6 @@ pub(crate) fn trust_readiness( } } -/// Mirrors upstream `HookStateToml` (`config/src/hook_config.rs`) exactly: -/// both fields optional, no `deny_unknown_fields` (an unrecognized extra key -/// is ignored, matching upstream). Deriving `Deserialize` from this shape -/// (rather than reading `enabled`/`trusted_hash` independently) is what lets -/// `read_hook_state` reject the whole entry, not just one bad field, exactly -/// as upstream's `hook_states_from_stack` does. #[derive(Debug, Default, Clone, serde::Deserialize)] struct HookStateEntry { #[serde(default)] @@ -162,17 +87,6 @@ struct HookStateEntry { trusted_hash: Option, } -/// Read `hooks.state.""` from the user's Codex config, treating a -/// missing config file as "no state recorded" (a normal, common state) rather -/// than an error. A config file that exists but cannot be read or parsed is -/// an error, since doctor cannot tell whether trust was actually granted. -/// -/// A present entry that fails to deserialize as a whole (e.g. `enabled` set -/// to a non-boolean) is treated as absent, matching upstream -/// `hook_states_from_stack`'s `Err(_) => continue`: Codex never salvages -/// individual fields from a malformed state entry, so neither does doctor — -/// a malformed entry must never read as `Trusted` just because its -/// `trusted_hash` string happens to be well-formed. fn read_hook_state(config_path: &Path, key: &str) -> Result { let contents = match std::fs::read_to_string(config_path) { Ok(contents) => contents, @@ -186,9 +100,6 @@ fn read_hook_state(config_path: &Path, key: &str) -> Result Result]}` shape, canonicalize (recursively sort object -/// keys, matching `fingerprint::canonical_json`), and SHA-256 the compact -/// JSON encoding. pub(crate) fn hash_command_handler( event: &str, matcher: Option<&str>, @@ -319,8 +222,6 @@ fn version_for_canonical_json(value: &Value) -> String { format!("sha256:{hex}") } -/// Recursively sort object keys, matching `fingerprint::canonical_json` -/// exactly (arrays keep their order; scalars pass through unchanged). fn canonical_json(value: &Value) -> Value { match value { Value::Object(map) => { @@ -568,9 +469,6 @@ mod tests { assert!(matches!(readiness, TrustReadiness::Unknown(_))); } - /// Writes `[hooks.state.""]` plus - /// `body` verbatim into a fresh `$CODEX_HOME/config.toml`, returning the - /// `TrustContext` pointed at it. fn write_state_toml( dir: &std::path::Path, label: &str, @@ -597,10 +495,6 @@ mod tests { #[test] fn trust_readiness_ignores_the_whole_entry_when_enabled_has_the_wrong_type() { - // Upstream deserializes the complete `HookStateToml` entry; a - // present field with the wrong type fails the whole entry, so a - // syntactically-correct `trusted_hash` next to it must never be - // salvaged into a false `Trusted` result. let dir = temp_dir("malformed-enabled"); let hooks_json = dir.join("hooks.json"); fs::write(&hooks_json, "{}").unwrap(); @@ -629,12 +523,6 @@ mod tests { fs::write(&hooks_json, "{}").unwrap(); let handler = bare_command_handler(); - // `enabled = false` here is the distinguishing signal: if only the - // malformed `trusted_hash` field were dropped in isolation, - // `enabled = false` would still be honored and this would read - // `Disabled`. The correct whole-entry-drop behavior discards - // `enabled` too, so the result must be `Untrusted` (the same as no - // entry at all). let context = write_state_toml( &dir, "malformed-hash-type", @@ -663,9 +551,6 @@ mod tests { let codex_home = dir.join("codex-home-malformed-entry"); fs::create_dir_all(&codex_home).unwrap(); - // The entry itself is a plain string, not a table: cannot - // deserialize as `HookStateToml` at all, so it must not panic and - // must fall back to "no state recorded" like a missing entry. fs::write( codex_home.join("config.toml"), format!("[hooks.state]\n\"{escaped_key}\" = \"not a table\"\n"), diff --git a/cli/src/services/command_registry.rs b/cli/src/services/command_registry.rs index 331ebbe6e..1723364a5 100644 --- a/cli/src/services/command_registry.rs +++ b/cli/src/services/command_registry.rs @@ -18,11 +18,6 @@ const DEFAULT_COMMAND_NAMES: &[&str] = &[ services::version::NAME, ]; -/// Static runtime command dispatcher for all known CLI commands. -/// -/// Parsed command requests are represented as enum variants instead of boxed -/// trait objects. Each variant delegates to the same service-owned command -/// implementation used before the static-dispatch migration. pub enum RuntimeCommand { Help(services::help::command::HelpCommand), HelpText(services::help::command::HelpTextCommand), @@ -79,10 +74,6 @@ impl RuntimeCommand { } } -/// Statically populated command catalog. -/// -/// The catalog owns deterministic command-name lookup only. Per-invocation -/// command payloads are built by the parse layer as [`RuntimeCommand`] variants. pub struct CommandRegistry { names: &'static [&'static str], } @@ -99,7 +90,6 @@ impl Default for CommandRegistry { } } -/// Build the default deterministic command catalog with all known commands. pub fn build_default_registry() -> CommandRegistry { CommandRegistry { names: DEFAULT_COMMAND_NAMES, diff --git a/cli/src/services/config/policy.rs b/cli/src/services/config/policy.rs index b64ac1904..7249d3792 100644 --- a/cli/src/services/config/policy.rs +++ b/cli/src/services/config/policy.rs @@ -1,11 +1,3 @@ -//! Bash-policy and attribution-hooks semantic validation, merge helpers, -//! and policy rendering. -//! -//! This submodule owns built-in/custom bash-policy validation, duplicate/conflict/ -//! redundancy checks, attribution-hooks config parsing helpers, policy resolved-data -//! structs, and policy-specific rendering. The parent `mod.rs` re-exports items -//! needed by resolution and rendering consumers. - use std::path::Path; use std::sync::OnceLock; diff --git a/cli/src/services/config/resolver.rs b/cli/src/services/config/resolver.rs index bcc31e42d..5564b4b8e 100644 --- a/cli/src/services/config/resolver.rs +++ b/cli/src/services/config/resolver.rs @@ -1,9 +1,3 @@ -//! Runtime config discovery, merge, and precedence resolution. -//! -//! This submodule owns config-file discovery, file-layer merging, -//! env/flag/default precedence, auth-key resolution, observability resolution, -//! and default-discovered invalid-file degradation. - use std::path::{Path, PathBuf}; use anyhow::{anyhow, bail, Context, Result}; @@ -1009,9 +1003,6 @@ pub(crate) fn get_database_retry_config() -> Option<&'static DatabaseRetryConfig DATABASE_RETRY_CONFIG.get() } -/// Resolve the full runtime config from the environment and initialize the -/// database retry `OnceLock`. Silently ignores errors — if the config cannot -/// be resolved, DB adapters fall back to hardcoded defaults. pub(crate) fn init_database_retry_config_from_environment(cwd: &Path) { if let Ok(runtime) = resolve_runtime_config( &ConfigRequest { diff --git a/cli/src/services/config/schema.rs b/cli/src/services/config/schema.rs index 1307f36ab..3c8c3369f 100644 --- a/cli/src/services/config/schema.rs +++ b/cli/src/services/config/schema.rs @@ -1,13 +1,3 @@ -//! Config schema embedding, JSON validation, serde DTO definitions, -//! and config-file load/parse helpers. -//! -//! This submodule owns the JSON Schema constant/validator, top-level -//! allowed-key validation, typed config-file deserialization, and the -//! file-parse orchestration that bridges schema validation to the -//! runtime config model. Policy-specific semantic validation (bash-policy -//! preset/custom conflict and redundancy checks) remains in the parent -//! module and is called through `super::` from parse helpers here. - use std::path::Path; use std::sync::OnceLock; diff --git a/cli/src/services/config/types.rs b/cli/src/services/config/types.rs index 46bc5fb52..6e4eef3c7 100644 --- a/cli/src/services/config/types.rs +++ b/cli/src/services/config/types.rs @@ -1,10 +1,3 @@ -//! Shared config types, enums, constants, and source metadata. -//! -//! This submodule owns the stable config primitives that are consumed across -//! multiple services. The parent `mod.rs` re-exports everything here through -//! `pub use types::*` so that existing `services::config::TypeName` imports -//! continue to work unchanged. - use std::path::PathBuf; use clap::ValueEnum; @@ -389,9 +382,6 @@ impl IntegrationTargetId { } } -/// Validate one `integrations.optional_workflows` id against the build-generated -/// optional-workflow catalog. Ids are not enumerated in Rust, so a workflow -/// marked optional in the Pkl catalog needs no change here. pub(crate) fn parse_optional_workflow_id(raw: &str, source: &str) -> anyhow::Result { if crate::services::setup::OPTIONAL_WORKFLOWS .iter() diff --git a/cli/src/services/db/encryption_key.rs b/cli/src/services/db/encryption_key.rs index 3054d823c..87ebcfa82 100644 --- a/cli/src/services/db/encryption_key.rs +++ b/cli/src/services/db/encryption_key.rs @@ -86,12 +86,6 @@ enum CredentialStorePlatform { Unsupported, } -/// Guards the one-time registration of the platform-native credential store. -/// -/// `OnceLock::get_or_try_init` is still unstable in the effective stable -/// toolchain, so a small atomic in-progress guard serializes fallible -/// initialization. The `OnceLock` is set only after success; on panic or -/// error, the in-progress guard is released and the next caller can retry. static DEFAULT_STORE: OnceLock = OnceLock::new(); static DEFAULT_STORE_INITIALIZING: AtomicBool = AtomicBool::new(false); @@ -364,7 +358,6 @@ fn derive_env_encryption_key(secret: &str) -> Result { Ok(hex_encode(&Sha256::digest(secret.as_bytes()))) } -/// Generate a 64-character lowercase hex key from 32 random bytes. fn generate_key() -> String { use rand::Rng; @@ -372,7 +365,6 @@ fn generate_key() -> String { hex_encode(&key) } -/// Hex-encode a byte slice into a lowercase hex string. fn hex_encode(bytes: &[u8]) -> String { use std::fmt::Write; diff --git a/cli/src/services/db/mod.rs b/cli/src/services/db/mod.rs index b09da5d47..65001b007 100644 --- a/cli/src/services/db/mod.rs +++ b/cli/src/services/db/mod.rs @@ -1,9 +1,3 @@ -//! Shared Turso database infrastructure. -//! -//! Provides a generic `TursoDb` adapter that wraps Turso connection -//! management, tokio runtime bridging, and embedded migration execution for -//! service-specific database specs. - use std::{ fs, marker::PhantomData, @@ -51,22 +45,16 @@ pub enum DatabaseKind { Auth, } -/// Service-specific Turso database configuration. pub trait DbSpec { - /// Human-readable database name used in diagnostics. fn db_name() -> &'static str; - /// Canonical database file path. fn db_path() -> Result; - /// Ordered embedded migration SQL files as `(id, sql)` pairs. fn migrations() -> &'static [(&'static str, &'static str)]; - /// Closed database identity selecting retry configuration and contention policy. const KIND: DatabaseKind; } -/// Collect common filesystem health problems for a Turso database path. pub fn collect_db_path_health(db_name: &str, db_path: &Path, problems: &mut Vec) { let db_name_title = sentence_case(db_name); @@ -139,7 +127,6 @@ pub fn collect_db_path_health(db_name: &str, db_path: &Path, problems: &mut Vec< } } -/// Create the parent directory for a Turso database path. pub fn bootstrap_db_parent(db_name: &str, db_path: &Path) -> Result { let parent = db_path .parent() @@ -226,10 +213,6 @@ async fn apply_migration( id: &str, sql: &str, ) -> Result<()> { - // Migration files may contain multiple statements (the repository - // Agent Trace baseline is one multi-statement schema file), so batch - // execution is required; `execute` would stop after the first - // statement. conn.execute_batch(sql) .await .map_err(|e| anyhow::anyhow!("{db_name} migration {id} failed: {e}"))?; @@ -240,9 +223,6 @@ async fn apply_migration( Ok(()) } -/// Body of [`TursoDb::execute_transactional_insert_pair_if_absent`], run -/// against an already-open transaction. Kept as a standalone `async fn` so -/// the caller can uniformly commit on `Ok` and roll back on `Err`. #[allow(clippy::too_many_arguments)] async fn execute_insert_pair_if_absent_body( tx: &turso::transaction::Transaction<'_>, @@ -719,12 +699,6 @@ fn busy_timeout_from_config( ) } -/// Resolve the Agent Trace write-contention deadline for `M`. -/// -/// The deadline decides whether another outer write-contention retry may -/// start; it does not interrupt a running Turso operation. It is taken from -/// `policies.database_retry.agent_trace_db.contention_deadline_ms` when -/// configured. Every other database resolves to zero. fn resolve_contention_deadline() -> std::time::Duration { contention_deadline_from_config::(crate::services::config::get_database_retry_config()) } @@ -900,7 +874,6 @@ fn contention_exhausted_error( ) } -/// Install `busy_timeout` on `conn`; a zero timeout leaves the handler unset. fn apply_busy_timeout( conn: &turso::Connection, db_name: &str, @@ -943,10 +916,6 @@ pub enum ExistingDbOpen { } impl TursoDb { - /// Open or create the database at the spec-provided canonical path. - /// - /// Parent directories are created automatically. Migrations are run after - /// the database connection is established. pub async fn new() -> Result { let db = Self::open_without_migrations().await?; @@ -957,11 +926,6 @@ impl TursoDb { Ok(db) } - /// Open or create the database at an explicit path. - /// - /// Parent directories are created automatically. Migrations are run after - /// the database connection is established. The service-specific retry and - /// migration configuration still comes from `M`. pub async fn new_at(db_path: impl AsRef) -> Result { let db = Self::open_without_migrations_at(db_path).await?; @@ -972,12 +936,6 @@ impl TursoDb { Ok(db) } - /// Open or create the database at the spec-provided canonical path without - /// running embedded migrations. - /// - /// Parent directories are created automatically and the connection-open - /// retry policy is preserved. Runtime callers that use this path are - /// responsible for verifying schema readiness before query/write work. pub async fn open_without_migrations() -> Result { let db_name = M::db_name(); let db_path = M::db_path().with_context(|| format!("failed to resolve {db_name} path"))?; @@ -1042,14 +1000,6 @@ impl TursoDb { }) } - /// Execute a SQL statement that does not return rows. - /// - /// # Arguments - /// * `sql` - SQL statement, which may contain `?` placeholders. - /// * `params` - Parameter values implementing `IntoParams`. - /// - /// # Returns - /// Number of rows affected. pub async fn execute(&self, sql: &str, params: impl turso::params::IntoParams) -> Result { let params = turso::params::IntoParams::into_params(params).map_err(|e| { anyhow::anyhow!("{} parameter conversion failed: {sql}: {e}", M::db_name()) @@ -1102,28 +1052,6 @@ impl TursoDb { .await } - /// Run an "insert row pair if absent" write transaction. - /// - /// If `exists_sql` (bound to `exists_params`) finds a matching row, no - /// insert statements run, the no-write transaction commits, and this - /// returns `false`. Otherwise `first_sql` then `second_sql` execute in order inside one - /// `BEGIN IMMEDIATE` transaction and commit together, returning `true`. - /// `BEGIN IMMEDIATE` serializes concurrent callers against the same - /// database file, so the existence check and both inserts are never - /// interleaved with another writer's attempt. The whole attempt is - /// retried as one unit on transient failure. - /// - /// `fail_before_second` is a test-only hook: when `true`, an error is - /// forced immediately after `first_sql` succeeds and before `second_sql` - /// runs or the transaction commits, so callers can prove the whole - /// transaction — including the already-executed `first_sql` — rolls - /// back together. - /// - /// Takes `&mut self` and begins the transaction with the checked - /// `Transaction::new(&mut Connection, ..)`, so the exclusive borrow spans - /// the whole transaction and no other operation on this adapter can run - /// inside it. Dropping the future uncommitted schedules a rollback that - /// runs on the connection's next use rather than immediately. #[allow(clippy::too_many_arguments)] pub async fn execute_transactional_insert_pair_if_absent( &mut self, @@ -1174,7 +1102,6 @@ impl TursoDb { .await } - /// Execute a SQL query and synchronously map all returned rows. pub async fn query_map( &self, sql: &str, @@ -1230,14 +1157,6 @@ impl TursoDb { Ok(results) } - /// Run a compare-and-swap guard plus ordered statements in one - /// `BEGIN IMMEDIATE` transaction. - /// - /// Takes `&mut self` and begins the transaction with the checked - /// `Transaction::new(&mut Connection, ..)`, so the exclusive borrow spans - /// the whole transaction and no other operation on this adapter can run - /// inside it. Dropping the future uncommitted schedules a rollback that - /// runs on the connection's next use rather than immediately. pub async fn execute_transactional_cas_batch( &mut self, operation_name: &str, @@ -1273,22 +1192,10 @@ impl TursoDb { } } - /// Run all embedded migrations in order. - /// - /// Applied migration IDs are recorded in `__sce_migrations` so later - /// initializations apply only migrations that were not already recorded. - /// Existing databases without migration metadata are brought forward by - /// re-applying the current idempotent migration set and recording each ID. pub async fn run_migrations(&self) -> Result<()> { self.core.run_migrations().await } - /// Run a passive WAL checkpoint (`PRAGMA wal_checkpoint(PASSIVE)`). - /// - /// PASSIVE checkpoints only what is currently safe to move from the WAL - /// into the main database file and never blocks on active readers or - /// writers, so it does not guarantee WAL truncation. Safe to call - /// repeatedly. Routine maintenance only; not a durability boundary. pub async fn passive_checkpoint(&self) -> Result<()> { let operation_name = format!("checkpoint {} database WAL", M::db_name()); @@ -1324,12 +1231,6 @@ impl TursoDb { .await } - /// Check migration metadata for problems that would prevent safe hook - /// runtime access. - /// - /// Returns a list of problems: missing migration metadata table, - /// incomplete applied migrations, or unexpected extra migrations. - /// An empty list means the schema is ready. pub async fn migration_metadata_problems(&self) -> Result> { let migration_table_exists = self.query_map( "SELECT name FROM sqlite_master WHERE type = 'table' AND name = '__sce_migrations' LIMIT 1", @@ -1386,12 +1287,6 @@ impl TursoDb { Ok(problems) } - /// Verify that the database schema needed by hook runtime readers and - /// writers already exists. - /// - /// This check is intentionally non-mutating. Missing or incomplete schema - /// is reported with the provided setup guidance instead of running - /// migrations from a high-frequency hook path. pub async fn ensure_schema_ready(&self, setup_guidance: &str) -> Result<()> { let problems = self.migration_metadata_problems().await?; @@ -1567,14 +1462,6 @@ impl EncryptedTursoDb { Ok(conn) } - /// Execute a SQL statement that does not return rows. - /// - /// # Arguments - /// * `sql` - SQL statement, which may contain `?` placeholders. - /// * `params` - Parameter values implementing `IntoParams`. - /// - /// # Returns - /// Number of rows affected. pub async fn execute(&self, sql: &str, params: impl turso::params::IntoParams) -> Result { let params = turso::params::IntoParams::into_params(params).map_err(|e| { anyhow::anyhow!("{} parameter conversion failed: {sql}: {e}", M::db_name()) @@ -1599,7 +1486,6 @@ impl EncryptedTursoDb { .await } - /// Execute a SQL query and synchronously map all returned rows. pub async fn query_map( &self, sql: &str, diff --git a/cli/src/services/default_paths.rs b/cli/src/services/default_paths.rs index 20ece4ef3..defd9e8e0 100644 --- a/cli/src/services/default_paths.rs +++ b/cli/src/services/default_paths.rs @@ -241,11 +241,6 @@ mod roots { } } -/// Returns the canonical path to the local Turso database file. -/// -/// The path is `/sce/local.db`, where `state_root` comes -/// from the shared default-path catalog (`XDG_STATE_HOME` or platform -/// equivalent). pub fn local_db_path() -> anyhow::Result { Ok(sce_state_dir()?.join("local.db")) } @@ -262,8 +257,6 @@ pub fn agent_trace_db_path_for_repository(repository_id: &str) -> anyhow::Result agent_trace_db_path_for_repository_at(&state_root, repository_id) } -/// Builds the repository-scoped Agent Trace database path under an explicit -/// state root: `/sce/repos//agent-trace.db`. pub fn agent_trace_db_path_for_repository_at( state_root: &std::path::Path, repository_id: &str, @@ -272,8 +265,6 @@ pub fn agent_trace_db_path_for_repository_at( if repository_id.is_empty() { anyhow::bail!("repository ID must not be empty when resolving Agent Trace DB path"); } - // The repository ID becomes a single path segment; reject anything that - // could escape the `repos/` directory. if repository_id.contains(['/', '\\']) || repository_id == "." || repository_id == ".." { anyhow::bail!("repository ID '{repository_id}' is not a valid path segment"); } @@ -285,10 +276,6 @@ pub fn agent_trace_db_path_for_repository_at( .join("agent-trace.db")) } -/// Returns the canonical default observability log directory. -/// -/// The path is `/sce/logs`, where `state_root` comes from the -/// shared default-path catalog (`XDG_STATE_HOME` or platform equivalent). pub fn observability_log_dir() -> anyhow::Result { Ok(sce_state_dir()?.join("logs")) } @@ -349,9 +336,6 @@ pub(crate) mod pi_asset { pub const EXTENSIONS_DIR: &str = "extensions"; } -/// Codex embedded-asset relative paths keep their own `.agents/`/`.codex/` -/// output-root prefix (unlike OpenCode/Claude/Pi, whose relative paths are -/// stripped of their single root), so `SKILLS_DIR` carries that prefix too. pub(crate) mod codex_asset { pub const SKILLS_DIR: &str = ".agents/skills"; } @@ -485,9 +469,6 @@ impl InstallTargetPaths { self.repo_root.join(repo_dir::PI) } - /// Codex has two output roots (`.agents/` for skills, `.codex/` for - /// hooks), both already embedded as prefixes on `CODEX_EMBEDDED_ASSETS` - /// relative paths, so the destination root is the repository root itself. pub(crate) fn codex_target_dir(&self) -> PathBuf { self.repo_root.clone() } diff --git a/cli/src/services/doctor/inspect.rs b/cli/src/services/doctor/inspect.rs index f2cd3d2ff..1ab76da05 100644 --- a/cli/src/services/doctor/inspect.rs +++ b/cli/src/services/doctor/inspect.rs @@ -724,12 +724,6 @@ fn inspect_hook_content_state_without_problem( } } -/// Classifies a hook's on-disk bytes against the canonical template by SCE -/// managed-block currency (merging the canonical block into `bytes` is a -/// no-op) rather than whole-file equality, so foreign content a repository -/// has appended around the block does not read as drift. An unbalanced or -/// partial managed block is also reported `Stale`, since it needs the same -/// `--fix` repair as a drifted one. fn hook_managed_block_content_state( hook_name: &str, bytes: &[u8], @@ -741,9 +735,6 @@ fn hook_managed_block_content_state( } } -/// Returns `true` when the doctor was able to check for integration targets -/// and found none (neither configured in `.sce/config.json` nor detected -/// via repo-root `.opencode/` / `.claude/` / `.pi/` directories). fn should_show_no_integrations_message( git_available: bool, bare_repository: bool, @@ -762,26 +753,21 @@ fn resolve_doctor_integration_targets(repository_root: &Path) -> Vec IntegrationContentState::Missing, codex_hook_config::RegistrationStructuralState::Stale => IntegrationContentState::Stale, codex_hook_config::RegistrationStructuralState::PresentAndCurrent => { let (Some(handler), Some(position)) = (&diagnosis.owned_handler, diagnosis.position) else { - // Structurally impossible: `PresentAndCurrent` always carries - // both. Treat defensively as stale rather than panicking. return IntegrationChildHealth { relative_path, path: hooks_json_path.to_path_buf(), @@ -2296,12 +2234,8 @@ fn sort_integration_children(children: &mut [IntegrationChildHealth]) { children.sort_by(|left, right| left.relative_path.cmp(&right.relative_path)); } -/// The relative path of the `OpenCode` merge-target asset within `.opencode/`. const OPENCODE_CONFIG_RELATIVE_PATH: &str = "opencode.json"; -/// Identifies the two setup assets that are installed by JSON merge -/// (`config_merge`) rather than whole-file replacement, and therefore need -/// SCE-fragment-based content inspection instead of byte-exact `sha256`. enum MergeTargetAsset { ClaudeSettings, OpenCodeConfig, @@ -2333,12 +2267,6 @@ fn build_integration_child_from_asset( } } -/// Content state for a merge-target asset: `Match` when the existing file -/// already carries a current, complete copy of the SCE-owned fragment -/// alongside whatever else it holds; `Mismatch` when that fragment is absent -/// or stale, or when the existing file cannot be parsed as JSON (a merge -/// cannot succeed either way, so both drift and hard-error surface the same -/// remediation: reinstall/`sce doctor --fix`). fn inspect_merge_target_asset_state( path: &Path, generated_bytes: &[u8], diff --git a/cli/src/services/doctor/render.rs b/cli/src/services/doctor/render.rs index d9bd16fc9..3c8372273 100644 --- a/cli/src/services/doctor/render.rs +++ b/cli/src/services/doctor/render.rs @@ -20,8 +20,6 @@ use crate::services::mutation_trace::runtime::{ ReconciliationCounts, ReconciliationFix, ReconciliationRecommendation, StateWarning, }; -/// Guidance message rendered in the Integrations section when no integration -/// targets are configured, detected, or both. const NO_INTEGRATIONS_MESSAGE: &str = "No integrations installed; run 'sce setup'"; pub(super) fn render_report(request: DoctorRequest, execution: &DoctorExecution) -> Result { @@ -621,10 +619,6 @@ fn asset_path_components(area: IntegrationArea, relative_path: &str) -> Vec None, }) .collect::>(); - // Codex's relative paths keep their own `.agents/`/`.codex/` output-root - // prefix (unlike OpenCode/Claude/Pi, whose relative paths are already - // stripped of their single root), so drop that leading root segment - // before the shared per-area prefix stripping below. if components .first() .is_some_and(|first| first == ".agents" || first == ".codex") diff --git a/cli/src/services/doctor/types.rs b/cli/src/services/doctor/types.rs index b10bc7067..209cee28f 100644 --- a/cli/src/services/doctor/types.rs +++ b/cli/src/services/doctor/types.rs @@ -143,8 +143,6 @@ impl IntegrationGroupKey { (IntegrationTarget::Pi, IntegrationArea::Extensions) => "Pi extensions", (IntegrationTarget::Codex, IntegrationArea::Skills) => "Codex skills", (IntegrationTarget::Codex, IntegrationArea::Hooks) => "Codex hooks", - // These combinations are not produced by inspection, but retaining - // deterministic labels keeps the key total for future targets/areas. (IntegrationTarget::Pi, IntegrationArea::Plugins) => "Pi plugins", (IntegrationTarget::Pi, IntegrationArea::Agents) => "Pi agents", (IntegrationTarget::Pi, IntegrationArea::Commands) => "Pi commands", @@ -194,30 +192,10 @@ pub(super) enum IntegrationContentState { Missing, Mismatch, ReadFailed(String), - /// A Codex hook registration is present but not canonical (an SCE-owned - /// handler exists but differs from the generated one, or duplicates - /// exist). Distinct from `Mismatch`, which describes a whole-file - /// byte/fragment comparison rather than one registration. Stale, - /// The whole `.codex/hooks.json` document could not be structurally - /// validated, so no per-registration state could be determined. Malformed(String), - /// The registration is structurally current, but Codex will not execute - /// it yet: disabled, never trusted, or trusted against stale content. - /// Carries a short machine-readable reason (`"untrusted"`, `"modified"`, - /// `"disabled"`, or `"unknown"`). NotTrusted(String), - /// The registration is structurally current, but Codex's effective - /// hook-discovery policy (`allow_managed_hooks_only = true`) discards - /// every project-owned hook source, so Codex will never even consider - /// this handler — independent of, and checked before, trust readiness. - /// Carries a human-readable explanation. PolicyBlocked(String), - /// Whether Codex's effective hook-discovery policy allows project hooks - /// could not be determined (no Codex executable, probe failure, timeout, - /// malformed response, etc.). Never treated as healthy: AC28 requires - /// proof Codex will actually execute the registration, and an unknown - /// policy is not proof. Carries a human-readable reason. PolicyUnknown(String), } diff --git a/cli/src/services/error.rs b/cli/src/services/error.rs index 6282b6fc1..22c60bdf9 100644 --- a/cli/src/services/error.rs +++ b/cli/src/services/error.rs @@ -363,9 +363,6 @@ impl std::fmt::Display for UserError { } } -/// Typed CLI-boundary error separating expected, user-facing failures from -/// internal failures whose technical `anyhow` source is preserved for -/// observability and diagnostic rendering. #[derive(Debug)] pub enum CliError { User { @@ -401,14 +398,10 @@ impl CliError { Self::internal(FailureClass::Dependency, source) } - /// Compatibility helper for parse failures still expressed as a plain - /// message rather than a live `anyhow::Error` source. pub fn parse(message: impl Into) -> Self { Self::internal(FailureClass::Parse, anyhow::Error::msg(message.into())) } - /// Compatibility helper for validation failures still expressed as a - /// plain message rather than a live `anyhow::Error` source. pub fn validation(message: impl Into) -> Self { Self::internal(FailureClass::Validation, anyhow::Error::msg(message.into())) } diff --git a/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/block.sh b/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/block.sh index dc24b9f88..b7ea515e2 100755 --- a/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/block.sh +++ b/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/block.sh @@ -1,8 +1,4 @@ #!/usr/bin/env bash -# T01 MCP-probe PreToolUse block hook. NOT SCE runtime code. -# Second PreToolUse handler (after dump.sh). Only blocks when the payload -# contains the marker "PLEASE_BLOCK_THIS_MCP_CALL"; otherwise a neutral no-op. -# Used to prove whether a blocked MCP call still emits PostToolUse. set -u payload="$(cat)" if printf '%s' "$payload" | grep -q 'PLEASE_BLOCK_THIS_MCP_CALL'; then diff --git a/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/dump.sh b/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/dump.sh index 7eac41549..842e9e075 100755 --- a/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/dump.sh +++ b/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/dump.sh @@ -1,12 +1,4 @@ #!/usr/bin/env bash -# T01 MCP-probe dump hook. NOT SCE runtime code. -# Reads the raw Codex hook payload from STDIN, records it verbatim, and exits 0 -# with empty stdout (a neutral no-op) so it never influences Codex behaviour. -# -# The capture directory is passed as $1 (absolute path, baked into the -# .codex/hooks.json command by run-probes.sh) because Codex runs hook commands -# with a cleared environment (see codex-rs/hooks/src/engine/command_runner.rs -# build_command: env_clear()). set -u CAP="${1:?capture dir arg missing}" mkdir -p "$CAP/events" 2>/dev/null || true @@ -19,9 +11,6 @@ event="$(printf '%s' "$payload" | sed -n 's/.*"hook_event_name":"\([^"]*\)".*/\1 tuid="$(printf '%s' "$payload" | sed -n 's/.*"tool_use_id":"\([^"]*\)".*/\1/p')" tname="$(printf '%s' "$payload" | sed -n 's/.*"tool_name":"\([^"]*\)".*/\1/p')" -# Concurrent hook deliveries (parallel MCP calls) run this script at the same -# time, so serialise the shared counter/log writes with a lock and give each -# delivery a collision-proof filename (nanosecond timestamp + pid). uniq="$(date -u +%Y%m%dT%H%M%S.%N)-$$" ( flock 9 n="$(cat "$CAP/.seq" 2>/dev/null || echo 0)" diff --git a/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/run-probes.sh b/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/run-probes.sh index 62b78dc36..161ddf5ca 100755 --- a/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/run-probes.sh +++ b/cli/src/services/hooks/codex_mutation_scope/fixtures/mcp_probe/run-probes.sh @@ -1,15 +1,4 @@ #!/usr/bin/env bash -# T01 MCP lifecycle probe driver. NOT SCE runtime code. -# -# Drives `codex exec` (codex-cli 0.153.4) against a tiny local stdio MCP server -# (server.py) wired into a scratch git repo, capturing every raw Codex hook -# payload plus git-observable mutation evidence. See NOTES.md "MCP probe manifest". -# -# Usage: -# MCP_PROBE_WORK=/abs/scratch/dir PY=/abs/python3 bash run-probes.sh [A B C ...] -# -# Requirements: codex on PATH, a working $CODEX_HOME/auth.json, network for the -# model. Nothing is written outside $MCP_PROBE_WORK and a private CODEX_HOME copy. set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" diff --git a/cli/src/services/hooks/commit_hooks/attribution_tests.rs b/cli/src/services/hooks/commit_hooks/attribution_tests.rs index c6a21f0c8..fb373dc38 100644 --- a/cli/src/services/hooks/commit_hooks/attribution_tests.rs +++ b/cli/src/services/hooks/commit_hooks/attribution_tests.rs @@ -138,8 +138,6 @@ impl HistoryRepo { Self::with_plan_paths(&[PLAN_PATH]) } - /// Every path receives the same plan content in every commit, so the - /// committed touched lines are identical at identical positions. fn with_plan_paths(paths: &[&str]) -> Self { let dir = tempfile::tempdir().expect("temp dir"); let root = dir.path(); @@ -1192,8 +1190,6 @@ async fn claude_structured_rows_resolve_paths_against_their_recorded_cwd() { } } -/// Claude actually edited this file from `cwd = /cli`; the repository -/// root holds a twin at [`PLAN_PATH`] with identical committed lines. const TWIN_PLAN_PATH: &str = "cli/context/plans/plan.md"; struct StructuredOutcome { @@ -1790,9 +1786,6 @@ struct PersistedDeletionTrace { committed: ParsedPatch, } -/// Runs the real post-commit capture, the exact-OID mutation resolver over -/// Turso-persisted events, and Agent Trace persistence. `HEAD` moves before -/// the resolver runs, so it must use the captured commit, not `HEAD`. async fn persist_deletion_trace( repo: &DeletionRepo, rows: &[MutationEventPageRow], diff --git a/cli/src/services/lifecycle.rs b/cli/src/services/lifecycle.rs index a683f7d92..dfb1003e0 100644 --- a/cli/src/services/lifecycle.rs +++ b/cli/src/services/lifecycle.rs @@ -266,9 +266,6 @@ impl LifecycleProvider { } } -/// Returns lifecycle providers in deterministic orchestration order. -/// -/// Provider order is config → `local_db` → `auth_db` → `agent_trace_db` → hooks when hook lifecycle behavior is requested. pub fn lifecycle_providers(include_hooks: bool) -> Vec { let mut providers = vec![ LifecycleProvider::Config, diff --git a/cli/src/services/local_db/mod.rs b/cli/src/services/local_db/mod.rs index bf6987392..28d7bdc17 100644 --- a/cli/src/services/local_db/mod.rs +++ b/cli/src/services/local_db/mod.rs @@ -1,5 +1,3 @@ -//! Local Turso database adapter. - use std::path::PathBuf; use anyhow::Result; @@ -11,7 +9,6 @@ use crate::services::{ pub mod lifecycle; -/// Local database configuration. pub struct LocalDbSpec; impl DbSpec for LocalDbSpec { @@ -30,5 +27,4 @@ impl DbSpec for LocalDbSpec { const KIND: DatabaseKind = DatabaseKind::Local; } -/// Local Turso database adapter. pub type LocalDb = TursoDb; diff --git a/cli/src/services/mutation_trace/lineage.rs b/cli/src/services/mutation_trace/lineage.rs index 77edf9643..bb742cb07 100644 --- a/cli/src/services/mutation_trace/lineage.rs +++ b/cli/src/services/mutation_trace/lineage.rs @@ -20,9 +20,6 @@ pub enum TransitionOrigin { } impl TransitionOrigin { - /// The provenance of a line this transition adds, and equally of a parent - /// line this transition removes: the effective actor is the transition, - /// never the actor that originally introduced the line. fn provenance(&self) -> LineProvenance { match self { TransitionOrigin::MutationAi(scope_id) => LineProvenance::MutationAi { @@ -40,9 +37,6 @@ pub struct LineageError { pub reason: String, } -/// Stable identity of one line of the exact parent commit: its parent-side -/// path and 1-based line number. It never changes while the line survives, -/// however other lines move around it. #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct ParentLineId { pub path: String, @@ -53,14 +47,9 @@ pub struct ParentLineId { struct ProvenanceLine { content: String, provenance: LineProvenance, - /// Set only for lines carried unchanged from the parent baseline; lines - /// introduced by any later transition have no parent identity. parent_identity: Option, } -/// The effective removal of a parent line: who removed it, and the content it -/// had. Its provenance is invalidated to `Unknown` once the same content is -/// plausibly restored, because text equality never proves identity. #[derive(Clone, Debug, Eq, PartialEq)] struct RemovalRecord { content: String, @@ -74,8 +63,6 @@ struct TransitionEffects { } impl TransitionEffects { - /// Records the parent identity of every removed line that has one; lines - /// introduced after the parent are removed without a trace. fn record_removed(&mut self, region: &[ProvenanceLine], offsets: &BTreeSet) { for offset in offsets { let line = ®ion[*offset]; @@ -94,8 +81,6 @@ impl TransitionEffects { pub struct MutationLineage { files: BTreeMap>, removals: BTreeMap, - /// Maps a tracked path to the parent path whose lines it holds, following - /// only renames the replay observed. parent_paths: BTreeMap, } @@ -144,8 +129,6 @@ impl MutationLineage { } } - /// Starts a lineage at the exact parent commit: every baseline line gets - /// a stable parent identity so later removals of it can be recorded. #[must_use] pub fn from_parent(files: &BTreeMap>) -> Self { MutationLineage { @@ -162,8 +145,6 @@ impl MutationLineage { } } - /// Restarts from an unanchored baseline. Every parent identity and - /// removal claim is dropped: none survives an unverified reset. pub fn reset_all(&mut self, files: &BTreeMap>) { *self = MutationLineage::from_baseline(files); } @@ -190,9 +171,6 @@ impl MutationLineage { Ok(()) } - /// An added line whose content equals an earlier-removed line of the same - /// parent file may be a restoration of it. Identity cannot be proven from - /// text, so the earlier removal claim becomes unknown for good. fn invalidate_restored_removals(&mut self, added: &[(String, String)]) { if self.removals.is_empty() { return; @@ -290,12 +268,10 @@ impl MutationLineage { } } - /// The tracked paths, including every path a rename moved lines into. pub fn tracked_paths(&self) -> impl Iterator { self.files.keys().map(String::as_str) } - /// Whether the tracked lines of `path` are exactly the lines of `content`. #[must_use] pub fn matches_content(&self, path: &str, content: Option<&str>) -> bool { let Some(tracked) = self.files.get(path) else { @@ -311,8 +287,6 @@ impl MutationLineage { .all(|(line, expected)| line.content == *expected) } - /// Makes every removal claim that the lines at `path` bear on unknown: - /// removals from `path` itself and from the parent path it holds. pub fn distrust_removals(&mut self, path: &str) { let parent_path = self.parent_paths.get(path).cloned(); for (identity, record) in &mut self.removals { @@ -322,13 +296,11 @@ impl MutationLineage { } } - /// The parent path whose lines `path` holds, when the replay established it. #[must_use] pub fn parent_path_of(&self, path: &str) -> Option<&str> { self.parent_paths.get(path).map(String::as_str) } - /// Every recorded parent-line removal with its effective provenance. #[cfg(test)] #[must_use] pub fn removed_identities(&self) -> Vec<(ParentLineId, LineProvenance)> { @@ -346,14 +318,6 @@ impl MutationLineage { .collect() } - /// Resolves the committed old-side removed lines of one canonical file - /// against the replayed parent identities. - /// - /// The committed file must hold the lines of `parent_path` by an observed - /// path history. Where the canonical diff and the replay disagree about - /// which parent lines were removed, they chose different alignments among - /// equal content, so every committed removal sharing that content is - /// ambiguous and stays `Unknown`. #[must_use] pub fn committed_removals( &self, diff --git a/cli/src/services/mutation_trace/lineage/tests.rs b/cli/src/services/mutation_trace/lineage/tests.rs index d1ccc97b3..d0ec88b80 100644 --- a/cli/src/services/mutation_trace/lineage/tests.rs +++ b/cli/src/services/mutation_trace/lineage/tests.rs @@ -637,14 +637,6 @@ fn distrusting_a_path_makes_its_removals_unknown() { ); } -/// Deterministic randomized checks of parent-line identity and removal -/// provenance against an independent reference model. -/// -/// The reference applies each generated operation directly to lines whose -/// parent identity is known by construction; the lineage only ever sees the -/// unified diff of that operation. The canonical committed diff is derived by -/// an independent LCS, so it can align duplicate content differently from the -/// replayed history. mod randomized_tests { use std::collections::BTreeMap; use std::fmt::Write as _; @@ -694,7 +686,6 @@ mod randomized_tests { } } - /// The reference's own mapping from transition to effective provenance. fn expected_provenance(origin: &TransitionOrigin) -> LineProvenance { match origin { TransitionOrigin::MutationAi(scope_id) => LineProvenance::MutationAi { @@ -733,8 +724,6 @@ mod randomized_tests { } } - /// Restoring content that an earlier transition removed makes that - /// removal unprovable; removals of the current transition are untouched. fn restore_check(&mut self, content: &str) { for (removed, provenance) in self.removals.values_mut() { if removed == content { @@ -788,8 +777,6 @@ mod randomized_tests { format!("diff --git a/{PATH} b/{PATH}\n--- a/{PATH}\n+++ b/{PATH}\n{hunk}") } - /// A whole-file hunk, as Git emits it, that removes `old[position]` when - /// `removed` and then inserts `added` at `position`. fn whole_file_hunk( old: &[String], position: usize, @@ -827,7 +814,6 @@ mod randomized_tests { ) } - /// Old-side line numbers an LCS diff from `old` to `new` removes. fn lcs_removed(old: &[&str], new: &[&str]) -> Vec { let mut table = vec![vec![0_usize; new.len() + 1]; old.len() + 1]; for i in (0..old.len()).rev() { @@ -855,8 +841,6 @@ mod randomized_tests { removed } - /// After a gap, no parent line can resolve as removed, whichever lines the - /// canonical diff names. fn committed_removal_results_are_unknown(lineage: &MutationLineage, parent: &[String]) -> bool { let every_parent_line: Vec<(u64, &str)> = parent .iter() diff --git a/cli/src/services/mutation_trace/mbt/driver.rs b/cli/src/services/mutation_trace/mbt/driver.rs index 8cc6669dd..dc68d54e5 100644 --- a/cli/src/services/mutation_trace/mbt/driver.rs +++ b/cli/src/services/mutation_trace/mbt/driver.rs @@ -1,16 +1,3 @@ -//! MBT driver: connects Quint Connect's generated/replayed traces to the -//! real `protocol.rs` transition functions. -//! -//! [`MutationCursorDriver::step`] dispatches on the `MbtAction` variant Quint -//! recorded — never on a before/after state diff — and every arm -//! unconditionally calls the corresponding `protocol::*` function with the -//! transported arguments, including on an `MbtAction` variant Quint produced -//! from a guarded/no-op path (T02's `mbtStutterAs` instrumentation): the -//! driver has no way to distinguish that case from a real transition, and -//! must not try to, since replaying the guarded call and comparing the -//! resulting no-op state against Quint is the point of the regressions in -//! T05. - use std::collections::{BTreeMap, BTreeSet}; use quint_connect::{switch, Config, Driver, Result, State, Step}; @@ -40,17 +27,6 @@ fn attempt_id(id: &str) -> AttemptId { AttemptId(id.to_string()) } -/// Replays a trace generated from/for `spec/mutation_cursor.qnt` through the -/// real `protocol.rs` functions. -/// -/// Holds exactly the state the plan authorizes: the pure protocol state -/// (refines `worktrees`/`scopes`/`externalTaint`/`processedEvents`/ -/// `attempts`/`mutationEvents`) plus `worktree_trees`, the driver-only -/// analogue of Quint's `worktreeTrees` var — the observed-tree input -/// `prepare`/`recover` take explicitly, since the pure kernel performs no Git -/// I/O. `MbtMutate` is the only action that touches `worktree_trees`; every -/// other action calls a `protocol::*` function, never reimplementing its -/// logic. pub(super) struct MutationCursorDriver { protocol: ProtocolState, worktree_trees: BTreeMap, @@ -172,7 +148,6 @@ impl MutationCursorDriver { self.protocol = protocol::recover(&self.protocol, worktree, observed_tree); } - /// Refines the explicit top-level `stutter` action: no state change. #[allow(clippy::unused_self)] fn mbt_stutter(&self) {} } diff --git a/cli/src/services/mutation_trace/mbt/mod.rs b/cli/src/services/mutation_trace/mbt/mod.rs index 99e8c3d12..afe07a210 100644 --- a/cli/src/services/mutation_trace/mbt/mod.rs +++ b/cli/src/services/mutation_trace/mbt/mod.rs @@ -1,13 +1,3 @@ -//! Model-based testing harness connecting the verified -//! `spec/mutation_cursor.qnt` model to the pure Rust refinement in -//! `super::protocol`/`super::types` via Quint Connect. -//! -//! Test-only (`#[cfg(test)]`, gated from `mutation_trace/mod.rs`): no -//! production code depends on this module, and it introduces no Git, -//! database, filesystem, environment, network, async, or lock I/O of its -//! own — every state transition is delegated to `super::protocol`'s pure -//! functions. - mod driver; mod model; mod tests; diff --git a/cli/src/services/mutation_trace/mbt/model.rs b/cli/src/services/mutation_trace/mbt/model.rs index 4876c3451..7b6491830 100644 --- a/cli/src/services/mutation_trace/mbt/model.rs +++ b/cli/src/services/mutation_trace/mbt/model.rs @@ -1,24 +1,3 @@ -//! Comparable model state and Quint ITF wire types for the MBT harness. -//! -//! Quint Connect deserializes trace state via the [`itf`] wire format, where -//! sum types serialize as `{ tag, value }` records (see the `quint-connect` -//! crate README's "Enums" section). The `Wire*` types here mirror that exact -//! shape for every Quint type reachable from `spec/mutation_cursor.qnt`'s -//! comparable state, then convert into this crate's own domain types -//! (`super::super::types`) via `From` impls, so [`ModelState`] and the values -//! [`super::driver::MutationCursorDriver`] extracts stay expressed in the -//! same production types the rest of `mutation_trace` uses. -//! -//! [`WireModelState`] and every semantic `Wire*` record use -//! `#[serde(deny_unknown_fields)]`, so a new Quint state variable or record -//! field fails deserialization instead of being silently dropped. `spec/ -//! mutation_cursor.qnt`'s verification-only variables (`scopeStartCount`, -//! `everTerminal`, every `*History` set, `evidenceAttempts`, `mbtAction`) are -//! given explicit [`IgnoredAny`] fields on [`WireModelState`], so they are a -//! deliberate exclusion from the compared state rather than an accidental -//! one — adding a new Quint variable forces a choice between modeling it as -//! semantic state or classifying it here as verification-only. - use std::collections::{BTreeMap, BTreeSet}; use serde::{de::IgnoredAny, Deserialize}; @@ -29,10 +8,6 @@ use super::super::types::{ WorktreeState, }; -// --------------------------------------------------------------------- -// Finite identity wire types (`spec/mutation_cursor.qnt`'s unit sum types) -// --------------------------------------------------------------------- - #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize)] #[serde(tag = "tag")] pub(super) enum WireWorktreeId { @@ -166,10 +141,6 @@ impl From for AttemptId { } } -// --------------------------------------------------------------------- -// Enum wire types -// --------------------------------------------------------------------- - #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize)] #[serde(tag = "tag")] pub(super) enum WireActorKind { @@ -246,10 +217,6 @@ impl From for AttemptStatus { } } -// --------------------------------------------------------------------- -// Structured wire types -// --------------------------------------------------------------------- - #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize)] #[serde(deny_unknown_fields)] pub(super) struct WireScopeEvent { @@ -414,17 +381,6 @@ impl From for MutationEvent { } } -// --------------------------------------------------------------------- -// Comparable model state -// --------------------------------------------------------------------- - -/// The comparable subset of `spec/mutation_cursor.qnt`'s state: every -/// variable named by AC5 (`worktrees`, `scopes`, `worktreeTrees`, -/// `externalTaint`, `processedEvents`, `attempts`, `mutationEvents`), -/// expressed in this crate's own domain types. Every other Quint variable is -/// verification-only and is dropped via an explicit [`IgnoredAny`] field on -/// [`WireModelState`], not by serde's default unknown-field handling — see -/// that type. #[derive(Debug, Eq, PartialEq, Deserialize)] #[serde(from = "WireModelState")] pub struct ModelState { @@ -437,12 +393,6 @@ pub struct ModelState { pub mutation_events: BTreeSet, } -/// Mirrors every `var` in `spec/mutation_cursor.qnt`'s state, so adding a -/// new Quint variable without updating this struct fails deserialization -/// (`deny_unknown_fields`) instead of silently vanishing. Verification-only -/// variables are still accepted, but only via an explicit [`IgnoredAny`] -/// field — modeling a new Quint variable here as `IgnoredAny` is a -/// deliberate "not semantic state" decision, not an oversight. #[allow( dead_code, reason = "verification-only Quint variables are deserialized to satisfy deny_unknown_fields and never read" @@ -450,7 +400,6 @@ pub struct ModelState { #[derive(Deserialize)] #[serde(rename_all = "camelCase", deny_unknown_fields)] struct WireModelState { - // Semantic state: compared against Rust via `ModelState`. worktrees: BTreeMap, scopes: BTreeMap, worktree_trees: BTreeMap, @@ -459,8 +408,6 @@ struct WireModelState { attempts: BTreeMap, mutation_events: BTreeSet, - // Verification-only: present in Quint's state for the model checker, - // not part of the Rust refinement comparison. scope_start_count: IgnoredAny, ever_terminal: IgnoredAny, cursor_history: IgnoredAny, diff --git a/cli/src/services/mutation_trace/mbt/tests.rs b/cli/src/services/mutation_trace/mbt/tests.rs index 9409a789d..49676e096 100644 --- a/cli/src/services/mutation_trace/mbt/tests.rs +++ b/cli/src/services/mutation_trace/mbt/tests.rs @@ -1,18 +1,7 @@ -//! Deterministic Quint Connect replays through the real `protocol.rs`. - use quint_connect::{quint_run, quint_test}; use super::driver::MutationCursorDriver; -/// Replays `testMbtDriverTransportsNonDefaultArguments` -/// (`spec/mutation_cursor.qnt`): `mutate(WT1, Tree3)` → -/// `prepare(Attempt5, Flush(WT1))` → `commitAttempt(Attempt5)`. Every value -/// here — worktree, tree, attempt, and boundary kind — differs from the -/// `WT0`/`Tree0`/`Tree1`/`Attempt0`/`Attempt1`/`Start`/`Advance`/`Close` -/// defaults the spec's other named scenarios use, so a passing replay proves -/// the driver transports the trace's actual concrete arguments into -/// `protocol::prepare`/`protocol::commit` rather than guessing or defaulting -/// them. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testMbtDriverTransportsNonDefaultArguments", @@ -22,8 +11,6 @@ fn mutation_cursor_transports_non_default_arguments() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testStartObservesBeforeActivation`: the freshness-boundary -/// semantics for a `Start` observation. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testStartObservesBeforeActivation", @@ -33,7 +20,6 @@ fn mutation_cursor_start_observes_before_activation() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testCloseObservesBeforeDeactivation`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testCloseObservesBeforeDeactivation", @@ -43,7 +29,6 @@ fn mutation_cursor_close_observes_before_deactivation() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testContendedIntervalsRemainAiContended`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testContendedIntervalsRemainAiContended", @@ -53,7 +38,6 @@ fn mutation_cursor_contended_intervals_remain_ai_contended() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testNoChangeHookReplayCannotStealFutureChange`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testNoChangeHookReplayCannotStealFutureChange", @@ -63,7 +47,6 @@ fn mutation_cursor_no_change_hook_replay_cannot_steal_future_change() -> impl Dr MutationCursorDriver::default() } -/// Replays `testConcurrentObservationsHaveOneWinner`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testConcurrentObservationsHaveOneWinner", @@ -73,7 +56,6 @@ fn mutation_cursor_concurrent_observations_have_one_winner() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testTaintInvalidatesPreparedObservation`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testTaintInvalidatesPreparedObservation", @@ -83,7 +65,6 @@ fn mutation_cursor_taint_invalidates_prepared_observation() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testRecoveryEstablishesBaseline`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testRecoveryEstablishesBaseline", @@ -93,7 +74,6 @@ fn mutation_cursor_recovery_establishes_baseline() -> impl Driver { MutationCursorDriver::default() } -/// Replays `testClosedScopeCannotReactivate`. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testClosedScopeCannotReactivate", @@ -130,14 +110,6 @@ fn mutation_cursor_unconfirmed_opencode_scope_blocks_cross_harness_attribution() MutationCursorDriver::default() } -/// Guarded-no-op regression: replays -/// `testMbtGuardedPrepareInvokesRealPrepare` -/// (`init.then(prepare(Attempt0, Start(...))).then(prepare(Attempt0, -/// Advance(...)))`), where the second `prepare` guards because `Attempt0` is -/// no longer `Available`. A passing replay proves the driver still calls -/// `protocol::prepare` on the guarded step — dispatch is on the `MbtAction` -/// variant Quint recorded, never skipped because Quint's own state happened -/// not to change — and independently reaches the same no-op outcome. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testMbtGuardedPrepareInvokesRealPrepare", @@ -147,12 +119,6 @@ fn mutation_cursor_guarded_prepare_invokes_real_prepare() -> impl Driver { MutationCursorDriver::default() } -/// Guarded-no-op regression: replays -/// `testMbtGuardedRecoverInvokesRealRecover` (`init.then(recover(WT0))`), -/// where `recover` guards because `WT0` is neither tainted, externally -/// tainted, nor needing rebaseline. A passing replay proves the driver still -/// calls `protocol::recover` on the guarded step and independently reaches -/// the same no-op outcome. #[quint_test( spec = "../spec/mutation_cursor.qnt", test = "testMbtGuardedRecoverInvokesRealRecover", @@ -162,9 +128,6 @@ fn mutation_cursor_guarded_recover_invokes_real_recover() -> impl Driver { MutationCursorDriver::default() } -/// Generated-trace refinement: replays Quint-generated randomized -/// traces through the real `protocol.rs`, comparing `ModelState` against -/// Quint's semantic state after every step. #[quint_run( spec = "../spec/mutation_cursor.qnt", max_samples = 200, @@ -175,15 +138,6 @@ fn mutation_cursor_generated_traces_refine_rust_protocol() -> impl Driver { MutationCursorDriver::default() } -/// Coverage backstop: `test = "test.*"` is passed through unescaped into -/// `quint test`'s `--match` as `^test.*$`, so this replays every top-level -/// `test...`-named `run` in `spec/mutation_cursor.qnt` — not just the -/// individually named scenarios above — through the real `protocol.rs`. Each -/// matched `run` is deterministic, so `max_samples = 1`. This exists so a new -/// named Quint scenario is automatically exercised here without also -/// requiring a new hand-written Rust wrapper; the individually named tests -/// above stay for readable `cargo test` failure output on the scenarios -/// worth naming. #[quint_test(spec = "../spec/mutation_cursor.qnt", test = "test.*", max_samples = 1)] fn mutation_cursor_all_named_scenarios_refine_rust_protocol() -> impl Driver { MutationCursorDriver::default() diff --git a/cli/src/services/mutation_trace/mod.rs b/cli/src/services/mutation_trace/mod.rs index 523017237..6c7b6c47b 100644 --- a/cli/src/services/mutation_trace/mod.rs +++ b/cli/src/services/mutation_trace/mod.rs @@ -1,148 +1,3 @@ -//! Pure Rust domain representation for the refinement of the verified -//! `spec/mutation_cursor.qnt` mutation-cursor protocol. -//! -//! This module defines the protocol's domain/state types, pure accessors, -//! `prepare`/`commitAttempt` transition logic for all four boundary kinds, -//! attribution derivation, mutation-event materialization, snapshot-failure -//! taint, database-failure external taint, scope abandonment, and recovery -//! with an explicit observed-tree input. This completes the action set the -//! plan scoped for `protocol.rs`. -//! -//! No Git, database, filesystem, environment, network, async, or lock I/O is -//! performed here. -//! -//! # Quint refinement matrix -//! -//! This module refines `spec/mutation_cursor.qnt`. The table below is -//! auditable against that file: for every relevant Quint element it names -//! the element, whether it is verification-only model instrumentation or a -//! semantic property, its Rust counterpart (if any), its classification, and -//! the concrete test or mechanism backing a non-verification-only -//! classification. A property is classified `verification-only` only when it -//! has no production semantic meaning beyond restating the consistency of -//! the omitted instrumentation itself — never merely because Quint happens -//! to state it using a history variable. -//! -//! ## Verification-only model instrumentation -//! -//! These concrete Quint checkpoint types and history/counter variables exist -//! only to state or prove properties against the finite, enumerated Quint -//! model. `ProtocolState` does not materialize any of them, and no -//! production Rust equivalent exists, unless a future adapter needs one for -//! another reason: `CursorCheckpoint`, `ProtocolCheckpoint`, -//! `ScopeCheckpoint`, `AbandonCheckpoint`, `StartCheckpoint`, -//! `RecoveryCheckpoint`, `DurableProtocolCheckpoint`, and the variables -//! `cursorHistory`, `protocolHistory`, `scopeHistory`, `abandonHistory`, -//! `startHistory`, `recoveryHistory`, `taintHistory`, `evidenceAttempts`, -//! `scopeStartCount`, `everTerminal`. -//! -//! Several Quint invariants exist solely to check the internal consistency -//! of that instrumentation (for example, that two checkpoints for the same -//! worktree/revision are equal, or that a history contains an entry matching -//! current state) rather than to state a fact about production behavior; -//! these are classified `verification-only` alongside the instrumentation -//! they describe: `CursorHistoryUniquePerWorktreeRevision`, -//! `CursorHistoryHasCurrentState`, `ProtocolHistoryUniquePerWorktreeRevision`, -//! `ProtocolHistoryHasCurrentState`, `ScopeHistoryUniquePerWorktreeRevision`, -//! `AbandonHistoryUniquePerWorktreeRevisionScope`, and the witness invariants -//! `HasExclusiveEvidence`/`HasContendedEvidence`/`HasUnscopedEvidence`/ -//! `HasRejectedAttempt` (reachability checks over the finite model, not -//! production properties). -//! -//! A verification-only **data structure** is not the same thing as a -//! verification-only **invariant**: `AbandonCreatesRebaselineRequirement`, -//! `MutationEventsMatchCursorHistory`, and -//! `MutationEventsCrossOnlyTrustworthyProtocolStates` are all *stated* using -//! the history variables above, but each proves a fact this module's -//! production transitions must actually uphold, so all three are classified -//! below as semantic properties, not verification-only. -//! -//! Quint's finite `SCOPES`/`WORKTREES` universes and `init`'s eager -//! population of every `ScopeState`/`WorktreeState` are **external adapter -//! responsibility**: this refinement's `ScopeId`/`WorktreeId` spaces are -//! unbounded runtime strings, so scope/worktree identity is materialized at -//! runtime by the future `coordinator.rs` layer rather than at protocol -//! startup (see the "Runtime scope materialization" assumption recorded in -//! the plan and in `context/cli/mutation-trace-protocol.md`). -//! -//! ## Semantic properties -//! -//! | Quint element | Rust counterpart | Classification | Backing mechanism | -//! |---|---|---|---| -//! | `CursorRevisionConsistent` | `WorktreeState::revision: u64` | enforced by Rust type | `u64` cannot represent a negative revision | -//! | `AbandonCreatesRebaselineRequirement` | `abandon` | preserved by transition tests | `abandon_transitions_a_live_scope_without_moving_the_cursor_or_changing_identity` proves, in one assertion set, that abandoning sets `Abandoned`+`needs_rebaseline`, leaves the cursor untouched, advances revision by exactly one, and leaves `mutation_events` equal to its pre-abandon value (no evidence emitted for the abandonment revision) | -//! | `FailureKindMatchesTaint` | `WorktreeState::{tainted, failure_kind}` | preserved by transition tests | `taint`/`recover` always set both fields together; `taint_changes_exactly_tainted_failure_kind_and_revision`, `recover_from_snapshot_taint_abandons_live_scopes_and_rebaselines_cursor`. `failure_kind` is the semantic health source of truth: `taint`, `recover`, and the coordinator's recovery admission read `failure_kind != Healthy`, never `tainted`, so a synthetic inconsistent pair is still classified by `failure_kind` (`recover_reads_health_from_failure_kind_and_takes_the_strong_path_when_tainted_disagrees`, `taint_is_a_no_op_when_failure_kind_is_unhealthy_even_if_tainted_disagrees`) | -//! | `TerminalScopesStayTerminal` | `ScopeStatus::{Closed, Abandoned}` | preserved by transition tests | `scope_started_at_most_once_and_stays_terminal_after_a_real_close`, `start_on_a_scope_abandoned_via_a_real_transition_never_reactivates_it` (terminal state reached via real transitions, then re-attempted) | -//! | `ScopeStartedAtMostOnce` | `commit`'s `Start`/`observes` gate | preserved by transition tests | `scope_started_at_most_once_and_stays_terminal_after_a_real_close` | -//! | `DatabaseFailureDoesNotMutateDurableProtocolState` | `database_failure` | preserved by transition tests | `database_failure_changes_exactly_external_taint` | -//! | `ExternalTaintNeverStrengthensAttribution` | `attribution_for` | preserved by transition tests | `attribution_for_is_ineligible_unscoped_when_worktree_is_externally_tainted_even_with_an_active_scope` | -//! | `RecoveryClearsExternalTaintOnlyAfterBaseline` | `recover` | preserved by transition tests | `recover_from_external_taint_abandons_live_scopes_and_clears_external_taint`, `database_failure_then_recover_clears_external_taint_and_rebaselines_cursor` (cursor rebaseline and `external_taint` clearing happen in the same transition) | -//! | `ScopeActorIdentityIsStable` | `ScopeState::actor_kind` | preserved by transition tests + external adapter responsibility | `abandon_transitions_a_live_scope_without_moving_the_cursor_or_changing_identity`; a future adapter must reject a conflicting `actor_kind` for an existing `ScopeId` rather than overwrite it | -//! | `NoNoopMutationEvents` | `commit`'s `changed` gate | preserved by transition tests | `commit_emits_no_mutation_event_for_a_no_op_tree_change` | -//! | `MutationEventsHavePositiveRevision` | `MutationEvent::revision` | preserved by transition tests | `commit` always sets a `MutationEvent`'s revision to the same checked `advanced_revision` (`revision.checked_add(1)`, never `0`) it writes to the worktree; `commit_emits_exactly_one_mutation_event_with_correct_attribution_boundary_and_revision_for_a_real_change` | -//! | `MutationEventUniquePerWorktreeRevision` | `ProtocolState::mutation_events` | preserved by transition tests | one `commit` call inserts at most one event, tagged with the freshly advanced revision, which strictly increases; `attribution_transitions_from_contended_to_exclusive_across_a_close_boundary` produces three events at three distinct revisions | -//! | `MutationFailureKindMatchesTaint` | `MutationEvent::{tainted, failure_kind}` | preserved by transition tests | copied verbatim from the pre-transition `WorktreeState` in `ResolvedAttempt::apply`, so `FailureKindMatchesTaint` carries over; `failure_kind` is the semantic field and `tainted` the redundant bit | -//! | `MutationEventsMatchCursorHistory` | `ResolvedAttempt::apply`'s `MutationEvent` construction | implemented directly + preserved by transition tests | `apply` derives `before_tree`/`after_tree`/`revision` from the same prepared attempt and the same `advanced_revision` the worktree update itself uses — they cannot diverge by construction; `commit_emits_exactly_one_mutation_event_with_correct_attribution_boundary_and_revision_for_a_real_change`, `attribution_transitions_from_contended_to_exclusive_across_a_close_boundary` (three events at three distinct revisions, each matching its own commit's before/after tree) | -//! | `MutationEventsCrossOnlyTrustworthyProtocolStates` | `commit`'s `changed` gate (`observed_change && !needs_rebaseline`) | implemented directly + preserved by transition tests | `changed` — the sole gate for `MutationEvent` construction — is `false` whenever the pre-transition worktree has `needs_rebaseline: true`, independent of whether a real tree change was observed; `needs_rebaseline_suppresses_mutation_event_even_when_commit_observes_a_real_tree_change` proves `commit` reaches `accepted && observes && observed_change` and still emits no event and leaves the cursor unmoved | -//! | `NeedsRebaselineSuppressesAttribution` | `attribution_for` | preserved by transition tests | `attribution_for_is_ineligible_unscoped_when_worktree_needs_rebaseline_even_with_an_active_scope` | -//! | `AiExclusiveRequiresExactlyOneActiveScope` | `Attribution::AiExclusive(ScopeId)` | implemented directly + preserved by transition tests | `Attribution::AiExclusive(ScopeId)` does not itself make an inconsistent scope count unrepresentable (a caller could construct it with any `ScopeId`); the guarantee comes from `attribution_for`'s own algorithm, which only reaches its `AiExclusive` branch when `live.len() == 1`, wrapping that exact scope; `attribution_for_is_ai_exclusive_for_exactly_one_live_scope` | -//! | `AiContendedRequiresMultipleActiveScopes` | `Attribution::AiContended` | preserved by transition tests | `attribution_for_is_ai_contended_for_multiple_live_scopes` | -//! | `RejectedAttemptsDoNotCommitEvidence` | `commit`'s rejection path | preserved by transition tests | rejection returns before the `changed`/`mutation_events` step is ever reached; `rejected_attempts_do_not_commit_evidence_across_a_mixed_accept_reject_sequence`, `competing_prepared_attempts_the_second_to_commit_is_rejected_by_cas`, `taint_invalidates_a_prepared_attempt_via_stale_revision` | -//! | `StartDoesNotAbandonExistingScopes` | `commit`'s `Start` scope transition | preserved by transition tests | only the boundary's own `scope_id` entry is ever written; `start_does_not_abandon_existing_scopes_multi_scope_sequence` | -//! -//! Five properties in the table above (`AbandonCreatesRebaselineRequirement`, -//! `MutationEventsMatchCursorHistory`, -//! `MutationEventsCrossOnlyTrustworthyProtocolStates`, -//! `RejectedAttemptsDoNotCommitEvidence`, `StartDoesNotAbandonExistingScopes`) -//! are stated in Quint using history variables (`abandonHistory`/ -//! `protocolHistory`/`cursorHistory`/`scopeHistory`, `evidenceAttempts`, -//! `startHistory`/`scopeHistory` respectively) but are classified -//! production-semantic, not `verification-only`: the instrumentation itself -//! is omitted, but the fact each one states — no evidence is emitted for an -//! abandonment revision, an emitted event's before/after tree and revision -//! always match the transition that produced it, no evidence crosses a -//! `needs_rebaseline` boundary, no rejected attempt's boundary contributes a -//! `MutationEvent`, and starting one scope never mutates another — is a real -//! guarantee this module's `commit`/`abandon` must uphold, independently -//! verified by the named tests above without needing the history variables -//! themselves. A verification-only *mechanism* never by itself demotes the -//! *property* it was used to prove. -//! -//! ## Bounded-integer revision refinement -//! -//! Quint's `revision: int` (`spec/mutation_cursor.qnt:39`) is an unbounded -//! integer; this refinement's `WorktreeState::revision: u64` is not. Every -//! action that advances a worktree's revision — `commit`, `taint`, -//! `abandon`, `recover` — routes through the private `next_revision` -//! (`revision.checked_add(1)`) helper in `protocol.rs` rather than a raw -//! `+ 1`, so a worktree already at `revision: u64::MAX` cannot be advanced -//! and cannot wrap to `0`. `taint`/`abandon`/`recover` always advance -//! revision when they execute, so each treats the headroom check as an -//! additional guarded no-op alongside their existing existence/precondition -//! guards, verified by `taint_does_not_wrap_revision_at_u64_max`, -//! `abandon_does_not_wrap_revision_at_u64_max`, and -//! `recover_does_not_wrap_revision_at_u64_max`, each starting from -//! `revision: u64::MAX` and proving the action is a no-op rather than a -//! wrap. -//! -//! `commit`'s `accepted` gate requires headroom only when this commit would -//! actually advance the worktree's revision: a non-`Flush` boundary always -//! advances revision when accepted, and a `Flush` advances revision only -//! when it observes a real tree change, so headroom is required for -//! non-`Flush` commits and for a `Flush` with an observed change, but *not* -//! for a `Flush` that observes no change — that commit may still succeed at -//! `revision: u64::MAX`, matching Quint's `commitAttempt`, since nothing -//! about it needs to advance. A rejected (would-be-overflowing) attempt is -//! rejected exactly like a stale one, with no cursor movement, scope -//! transition, processed-`EventKey` insertion, or `MutationEvent`. This -//! headroom guard has no Quint counterpart — Quint's `revision` never needs -//! one — so it is a Rust-only refinement precondition, verified by -//! `commit_that_would_advance_is_rejected_at_u64_max` (a commit that would -//! advance revision is rejected at `u64::MAX`) and -//! `no_change_flush_commits_at_u64_max_without_advancing_revision` (a -//! no-change `Flush` still commits successfully at `u64::MAX`, with revision -//! unchanged). - pub mod attribution; pub mod lineage; pub mod protocol; diff --git a/cli/src/services/mutation_trace/protocol.rs b/cli/src/services/mutation_trace/protocol.rs index b028109e8..37dfcbbfb 100644 --- a/cli/src/services/mutation_trace/protocol.rs +++ b/cli/src/services/mutation_trace/protocol.rs @@ -7,28 +7,10 @@ use super::types::{ WorktreeId, WorktreeState, }; -/// Advances a worktree revision counter by one, refusing to wrap past -/// `u64::MAX`. -/// -/// Quint's `revision: int` (`spec/mutation_cursor.qnt:39`) is an unbounded -/// integer; this refinement's `revision: u64` is not, so every action that -/// advances a worktree's revision — [`commit`], [`taint`], [`abandon`], and -/// [`recover`] — routes through this single checked helper rather than a raw -/// `+ 1`, so the same bounded-integer refinement guard applies uniformly -/// everywhere the counter can move. `None` signals that advancing would wrap, -/// which every caller treats as a guarded no-op/rejection rather than ever -/// wrapping the counter or committing partial state. fn next_revision(revision: u64) -> Option { revision.checked_add(1) } -/// The live scopes belonging to `worktree`, read from `state`. Refines -/// `liveScopesOn` (`spec/mutation_cursor.qnt:265-269`). -/// -/// The Quint function filters a fixed `SCOPES` universe by -/// `worktreeId == worktree and isLive(status)`. This refinement's `ScopeId` -/// space is unbounded (see `types.rs`'s module doc comment), so it filters -/// the known `state.scopes` map by the same predicate instead. pub fn live_scopes_on(state: &ProtocolState, worktree: &WorktreeId) -> BTreeSet { state .scopes @@ -38,15 +20,6 @@ pub fn live_scopes_on(state: &ProtocolState, worktree: &WorktreeId) -> BTreeSet< .collect() } -/// The mutation-evidence attribution for `worktree`, read from `state`. -/// Refines `attributionFor` (`spec/mutation_cursor.qnt:285-301`). -/// -/// `IneligibleUnscoped` when the worktree is unhealthy, externally tainted, -/// needs rebaseline, or has no live scopes; `AiExclusive` for exactly one -/// live scope; `AiContended` for more than one. An unresolvable worktree (no -/// durable state) also yields `IneligibleUnscoped`, matching the "no live -/// scopes" case, since the Quint model's `worktree` always resolves within -/// its finite domain and has no equivalent missing case to refine. pub fn attribution_for(state: &ProtocolState, worktree: &WorktreeId) -> Attribution { let live = live_scopes_on(state, worktree); let unhealthy = state @@ -91,8 +64,6 @@ pub fn has_unconfirmed_required_scope( }) } -/// Whether `boundary` closes a scope whose pre-boundary status in `state` is -/// `NeverSeen`. Refines `boundaryClosesNeverSeenScope`. pub fn boundary_closes_never_seen_scope(state: &ProtocolState, boundary: &Boundary) -> bool { is_close(boundary) && boundary_scope(boundary) @@ -100,14 +71,6 @@ pub fn boundary_closes_never_seen_scope(state: &ProtocolState, boundary: &Bounda .is_some_and(|scope_state| scope_state.status == ScopeStatus::NeverSeen) } -/// The attribution for a mutation observed at `boundary`, read from the -/// pre-boundary `state`. Refines `attributionForBoundary`. -/// -/// A `Close` of a `NeverSeen` scope is always `IneligibleUnscoped`: its -/// `Start` was never durably observed, so the boundary can neither confirm -/// nor attribute the change, whatever other scopes are live. Otherwise an -/// unconfirmed live confirmation-required scope suppresses attribution, and -/// the remaining cases fall through to [`attribution_for`]. pub fn attribution_for_boundary( state: &ProtocolState, worktree: &WorktreeId, @@ -123,20 +86,6 @@ pub fn attribution_for_boundary( attribution_for(state, worktree) } -/// Prepares `attempt` against `boundary`, snapshotting the worktree's current -/// `revision`/`cursor_tree` as the attempt's CAS baseline and `observed_tree` -/// as its target `after_tree`. Refines `prepareAvailable`/`prepare` -/// (`spec/mutation_cursor.qnt:417-453`). -/// -/// `observed_tree` corresponds to Quint's `worktreeTrees.get(worktree)`: the -/// currently observed tree at the boundary's resolved worktree, supplied by -/// the caller rather than read internally, since the pure kernel performs no -/// Git I/O. -/// -/// A no-op (refining Quint's `stutter`) when `attempt` already exists with a -/// status other than `Available`, when the boundary's worktree cannot be -/// resolved (an unregistered scope for a hook boundary), or when that -/// worktree has no durable state. pub fn prepare( state: &ProtocolState, attempt: AttemptId, @@ -172,33 +121,16 @@ pub fn prepare( next } -/// The computed evaluation flags `commitAttempt` derives before applying its -/// state transition, exposed for callers that need them without -/// reconstructing them from the returned state. #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] #[allow(clippy::struct_excessive_bools)] pub struct CommitEvaluation { - /// `fresh`: the attempt was `Prepared` against a CAS baseline - /// (`expected_revision`/`before_tree`) that still matches the worktree's - /// current `revision`/`cursor_tree`, the worktree is not externally - /// tainted, and, for hook boundaries, the event has not already been - /// processed. pub accepted: bool, - /// Whether this boundary observes live protocol state for its scope - /// (`Start` requires `NeverSeen`, `Advance` requires live, `Close` - /// accepts `NeverSeen` or live, `Flush` is always `true`). pub observes: bool, - /// `accepted and observes and before_tree != after_tree`. pub observed_change: bool, - /// `observed_change and not needs_rebaseline`. Gates whether [`commit`] - /// materializes a `MutationEvent` for this attempt. pub changed: bool, - /// `accepted and (not is_flush(boundary) or observed_change)`. pub advances_revision: bool, } -/// The result of evaluating and committing one prepared attempt: the -/// evaluation flags plus the resulting protocol state. #[derive(Clone, Debug, Eq, PartialEq)] pub struct CommitOutcome { pub evaluation: CommitEvaluation, @@ -217,8 +149,6 @@ pub fn commit(state: &ProtocolState, attempt: &AttemptId) -> CommitOutcome { CommitOutcome { evaluation, state } } -/// The prepared attempt and its boundary's resolved worktree/scope context, -/// read once and shared by evaluation and application. struct ResolvedAttempt { planned: AttemptState, boundary: Boundary, @@ -243,19 +173,6 @@ impl ResolvedAttempt { }) } - /// Refines the `fresh`/`observes`/`accepted`/`observedChange`/`changed`/ - /// `advancesRevision` computation at `spec/mutation_cursor.qnt:462-483`. - /// - /// `accepted` additionally requires revision headroom - /// ([`next_revision`]) — a Rust-only refinement guard with no Quint - /// counterpart, since Quint's `revision` is unbounded — but only when - /// this commit would actually advance the worktree's revision. - /// Non-`Flush` commits always advance revision when accepted, so they - /// always require headroom. A `Flush` advances revision only when it - /// observes a real tree change, so a fresh no-change `Flush` may still - /// commit at `revision: u64::MAX`, matching Quint: [`ResolvedAttempt::apply`] - /// never advances the revision for such a commit, so there is nothing - /// for the guard to protect there. fn evaluate(&self, state: &ProtocolState) -> CommitEvaluation { let current_scope = self .scope_id @@ -298,8 +215,6 @@ impl ResolvedAttempt { } } - /// Refines the accepted/rejected state transition at - /// `spec/mutation_cursor.qnt:503-660`. fn apply( &self, state: &ProtocolState, @@ -317,12 +232,6 @@ impl ResolvedAttempt { return next; } - // `evaluate` already proved that advancing the worktree's revision - // cannot wrap whenever `advances_revision` is true; this recomputes - // the same checked value rather than trusting a stored flag, so this - // function has no raw `+ 1` of its own. When `advances_revision` is - // false (a fresh no-change `Flush`), no headroom was required or - // proved, so no next revision is computed at all. let advanced_revision = if evaluation.advances_revision { Some( next_revision(self.worktree_state.revision) @@ -332,10 +241,6 @@ impl ResolvedAttempt { None }; - // `observes` already encodes the exact scope-status guard - // `commitAttempt` repeats for its own scope transition (`NeverSeen` - // for `Start`, `NeverSeen` or live for `Close`), so reusing it here - // cannot diverge from the spec's separately-stated guard. if let Some(scope_id) = &self.scope_id { if is_start(&self.boundary) && evaluation.observes { if let Some(entry) = next.scopes.get_mut(scope_id) { @@ -396,25 +301,6 @@ impl ResolvedAttempt { } } -/// Marks `worktree`'s Git snapshot capture as tainted by a snapshot failure. -/// Refines `taintHealthy`/`taint` (`spec/mutation_cursor.qnt:663-710`). -/// -/// Sets `tainted=true` and `failure_kind=SnapshotFailure`, advances -/// `revision` by one, and leaves `cursor_tree`/`needs_rebaseline` untouched. -/// A guarded no-op (refining Quint's `stutter`) when `worktree` is already -/// unhealthy (`failure_kind != Healthy`; `failure_kind` is the semantic -/// health source of truth and `tainted` is the redundant bit -/// `FailureKindMatchesTaint` keeps equal to it), already in `external_taint`, -/// has no durable state, or is -/// already at `revision: u64::MAX` (see [`next_revision`] — this last case -/// has no Quint counterpart either, since Quint's `revision` is unbounded). -/// -/// The missing-worktree case has no Quint counterpart: `WorktreeId` ranges -/// over the finite `WORKTREES` universe there, and `init` materializes a -/// `WorktreeState` for every member, so every `WorktreeId` already resolves. -/// This refinement's `WorktreeId` is an unbounded runtime value, so an -/// unknown worktree is unresolved kernel input rather than a state `taint` -/// may create — the same existence contract [`database_failure`] enforces. pub fn taint(state: &ProtocolState, worktree: &WorktreeId) -> ProtocolState { let Some(worktree_state) = state.worktrees.get(worktree) else { return state.clone(); @@ -442,24 +328,6 @@ pub fn taint(state: &ProtocolState, worktree: &WorktreeId) -> ProtocolState { next } -/// Records a database failure for `worktree` by adding it to -/// `external_taint`. Refines `recordDatabaseFailure`/`databaseFailure` -/// (`spec/mutation_cursor.qnt:712-737`). -/// -/// Changes `external_taint` only; every other durable worktree/scope field -/// stays as it was. A guarded no-op (refining Quint's `stutter`) when -/// `worktree` is already in `external_taint` or has no durable state. -/// -/// Quint's `WorktreeId` ranges over the finite `WORKTREES` universe, and -/// `init` materializes a `WorktreeState` for every member, so -/// `recordDatabaseFailure` has no explicit existence guard because there is -/// no state for it to guard against — every `WorktreeId` already resolves. -/// This refinement's `WorktreeId` is an unbounded runtime value, so a -/// referenced worktree must already exist in `ProtocolState.worktrees` -/// before this action may operate on it; an unknown `WorktreeId` is -/// unresolved kernel input, not a worktree this action may bring into -/// existence, and keeping `external_taint` a subset of known worktrees -/// matches `taint`'s own existence guard. pub fn database_failure(state: &ProtocolState, worktree: &WorktreeId) -> ProtocolState { if !state.worktrees.contains_key(worktree) || state.external_taint.contains(worktree) { return state.clone(); @@ -470,28 +338,6 @@ pub fn database_failure(state: &ProtocolState, worktree: &WorktreeId) -> Protoco next } -/// Abandons `scope`, ending its lifecycle. Refines `abandonLiveScope`/`abandon` -/// (`spec/mutation_cursor.qnt:739-805`). -/// -/// Transitions the scope to `Abandoned`, preserving its `actor_kind` and -/// `worktree_id` (scope identity stability), sets the owning worktree's -/// `needs_rebaseline=true`, advances `revision` by one, and leaves -/// `cursor_tree`/`tainted`/`failure_kind` untouched. A guarded no-op (refining -/// Quint's `stutter`) when the scope is not live — `NeverSeen`, `Closed`, and -/// `Abandoned` all stutter, so a terminal scope can never be reactivated or -/// abandoned again — when its worktree is externally tainted, or when its -/// worktree is already at `revision: u64::MAX` (see [`next_revision`]; no -/// Quint counterpart, since Quint's `revision` is unbounded). -/// -/// Quint's `abandon` resolves the owning worktree unconditionally from -/// `scopes.get(scope).worktreeId`, because the model's finite `SCOPES` -/// universe guarantees every `ScopeId` already has a `ScopeState`. This -/// refinement's `ScopeId` is an unbounded runtime value with no such -/// guarantee (see the runtime scope materialization contract in -/// `context/cli/mutation-trace-protocol.md`), so an unknown scope, or a scope -/// whose own `worktree_id` has no durable `WorktreeState`, is also a guarded -/// no-op — the same existence contract [`taint`]/[`database_failure`] -/// enforce. pub fn abandon(state: &ProtocolState, scope: &ScopeId) -> ProtocolState { let Some(scope_state) = state.scopes.get(scope) else { return state.clone(); @@ -528,32 +374,6 @@ pub fn abandon(state: &ProtocolState, scope: &ScopeId) -> ProtocolState { next } -/// Recovers `worktree`, re-baselining its cursor to the currently observed -/// tree and clearing its failure/rebaseline state. Refines -/// `recoverNeeded`/`recover` (`spec/mutation_cursor.qnt:807-886`). -/// -/// `observed_tree` corresponds to Quint's `worktreeTrees.get(worktree)`: the -/// currently observed tree, supplied by the caller rather than read -/// internally, since the pure kernel performs no Git I/O — the same -/// explicit-input contract [`prepare`] follows. -/// -/// Sets `cursor_tree=observed_tree`, `tainted=false`, -/// `failure_kind=Healthy`, `needs_rebaseline=false`, advances `revision` by -/// one, and removes `worktree` from `external_taint`. Health is read from -/// `failure_kind`, never from the redundant `tainted` bit. When -/// `failure_kind != Healthy` or the worktree is externally tainted, every -/// live scope on it is transitioned to `Abandoned` (preserving -/// `actor_kind`/`worktree_id`); a worktree recovering only from -/// `needs_rebaseline` (`failure_kind == Healthy`, not externally tainted) -/// preserves its live scopes untouched. -/// -/// A guarded no-op (refining Quint's `stutter`) when the worktree has -/// `failure_kind == Healthy`, is not externally tainted, and does not need -/// rebaseline; when -/// `worktree` has no durable state — the same existence contract -/// [`taint`]/[`database_failure`]/[`abandon`] enforce; or when `worktree` is -/// already at `revision: u64::MAX` (see [`next_revision`]; no Quint -/// counterpart, since Quint's `revision` is unbounded). pub fn recover( state: &ProtocolState, worktree: &WorktreeId, diff --git a/cli/src/services/mutation_trace/runtime/coordinator.rs b/cli/src/services/mutation_trace/runtime/coordinator.rs index ccb3c5aec..8e6aad96a 100644 --- a/cli/src/services/mutation_trace/runtime/coordinator.rs +++ b/cli/src/services/mutation_trace/runtime/coordinator.rs @@ -95,21 +95,10 @@ pub enum CoordinateError { revision: u64, }, LockAcquisition(anyhow::Error), - /// Inspecting or persisting the worktree-local external-taint marker failed. - /// Both operations run **before** any checkout-identity, DB, snapshot, or - /// protocol work, so no mutation boundary has committed and there is no - /// [`CoordinateOutcome`] to surface — the boundary is aborted fail-closed - /// with the fence left in whatever state it was in. ExternalTaintMarker { operation: ExternalTaintOperation, source: anyhow::Error, }, - /// The mutation boundary committed successfully to the Agent Trace DB and - /// produced a [`CoordinateOutcome`], but clearing the write-ahead - /// external-taint marker afterwards failed. The boundary did **not** fail: - /// `committed` carries the durable outcome (including any [`MutationEvent`]) - /// so the caller never loses it. The marker remains logically armed, so the - /// next invocation conservatively recovers. MarkerClearAfterCommit { source: anyhow::Error, #[allow( @@ -118,10 +107,6 @@ pub enum CoordinateError { )] committed: Box, }, - /// The caller-supplied Agent Trace DB provider returned `Err` after the - /// external-taint marker was already armed. The marker is intentionally - /// left in place so a later invocation treats the lost interval - /// conservatively. AgentTraceDbUnavailable(anyhow::Error), Other(anyhow::Error), } @@ -505,17 +490,6 @@ where }) } -/// Applies the admission-bounded provenance rule for a `Start` carrying -/// provenance, using the durable [`types::ScopeState`] that `register_scope` -/// just returned. -/// -/// An existing provenance row is always re-registered, so the store's immutable -/// session identity and first-observed model semantics stay authoritative on -/// every replay. A row may only be *created* while the durable scope is still -/// `NeverSeen` — a retry whose earlier attempt never committed the protocol -/// `Start`. Once the scope has crossed protocol admission, absent provenance -/// stays absent permanently: provenance describes its scope as observed at -/// admission, so it is never attached retroactively. async fn register_start_provenance( store: &MutationTraceStore<'_>, boundary: &RuntimeBoundary, diff --git a/cli/src/services/mutation_trace/runtime/external_taint.rs b/cli/src/services/mutation_trace/runtime/external_taint.rs index 9c2f89d88..840d51a5f 100644 --- a/cli/src/services/mutation_trace/runtime/external_taint.rs +++ b/cli/src/services/mutation_trace/runtime/external_taint.rs @@ -1,39 +1,12 @@ -//! External-taint marker primitive for the mutation-cursor runtime boundary. -//! -//! A worktree-local filesystem marker at `/sce/mutation-cursor-tainted`. -//! Its existence is its entire state: armed write-ahead at the start of the -//! protected runtime section, cleared only after a proven durable completion, and -//! read by a later invocation as the external signal that the previous -//! invocation never proved a trustworthy durable completion. -//! -//! Durability follows the repository's established durable-file pattern: -//! [`ExternalTaintMarker::persist`] creates and `fsync`s the marker file, and -//! both `persist` and [`ExternalTaintMarker::clear`] do a best-effort -//! `#[cfg(unix)]` parent-directory `sync_all` whose error is not propagated. This -//! protects against process error, non-graceful process exit, `SIGKILL`, and -//! normal runtime restart — not host power loss or a filesystem-level crash. -//! -//! The filesystem marker is never authoritative for normal cursor state, and it -//! is never deleted via `Drop`: only an explicit `clear()` after a successful -//! `CoordinateOutcome` removes it. - use std::fs::OpenOptions; use std::path::{Path, PathBuf}; use anyhow::{Context, Result}; -/// Subdirectory inside `/` where SCE runtime metadata lives. const SCE_RUNTIME_DIR: &str = "sce"; -/// File name for the external-taint marker inside `/sce/`. const MARKER_FILE: &str = "mutation-cursor-tainted"; -/// Worktree-local external-taint marker. -/// -/// Construct with [`ExternalTaintMarker::new`] from the worktree-specific Git -/// directory resolved by the runtime's Git snapshot service. -/// Two linked worktrees resolve to two different Git directories and therefore -/// two independent markers. #[derive(Debug, Clone)] pub struct ExternalTaintMarker { marker_dir: PathBuf, @@ -41,7 +14,6 @@ pub struct ExternalTaintMarker { } impl ExternalTaintMarker { - /// Builds the marker handle rooted at `/sce/mutation-cursor-tainted`. #[must_use] pub fn new(git_dir: &Path) -> Self { let marker_dir = git_dir.join(SCE_RUNTIME_DIR); @@ -52,12 +24,6 @@ impl ExternalTaintMarker { } } - /// Returns `true` when the marker file is present. - /// - /// # Errors - /// - /// Returns an error when the marker path cannot be inspected for a reason - /// other than absence. pub fn exists(&self) -> Result { match std::fs::symlink_metadata(&self.marker_path) { Ok(_) => Ok(true), @@ -71,14 +37,6 @@ impl ExternalTaintMarker { } } - /// Creates and `fsync`s the marker file. - /// - /// Idempotent: a marker that already exists is re-synced and left in place. - /// - /// # Errors - /// - /// Returns an error when the marker directory or file cannot be created or - /// synced. pub fn persist(&self) -> Result<()> { std::fs::create_dir_all(&self.marker_dir).with_context(|| { format!( @@ -111,13 +69,6 @@ impl ExternalTaintMarker { Ok(()) } - /// Removes the marker file. - /// - /// Idempotent: clearing an absent marker is success. - /// - /// # Errors - /// - /// Returns an error when the marker file exists but cannot be removed. pub fn clear(&self) -> Result<()> { match std::fs::remove_file(&self.marker_path) { Ok(()) => {} diff --git a/cli/src/services/mutation_trace/runtime/git_snapshot.rs b/cli/src/services/mutation_trace/runtime/git_snapshot.rs index 2f0d931db..56444a630 100644 --- a/cli/src/services/mutation_trace/runtime/git_snapshot.rs +++ b/cli/src/services/mutation_trace/runtime/git_snapshot.rs @@ -204,9 +204,6 @@ impl GitSnapshotService { .await } - /// Resolves the tree of `commit_oid` and, for a single-parent commit, the - /// tree of its first parent, by explicit object ID and never through `HEAD`. - /// Root and merge commits have no parent tree to anchor removals to. pub async fn committed_trees(&self, commit_oid: &str) -> Result { if commit_oid.is_empty() || !commit_oid.chars().all(|c| c.is_ascii_hexdigit()) { bail!("commit OID '{commit_oid}' is not a hexadecimal object ID"); @@ -502,12 +499,7 @@ pub struct PinnedRef { #[derive(Debug)] pub enum PinInventoryError { - /// `git for-each-ref` itself failed to execute or exited non-zero. Git(anyhow::Error), - /// A ref under the SCE namespace is not shaped like a `pin_tree` output: a - /// symbolic ref, a non-tree target, a name/target SHA mismatch, an - /// unparseable `for-each-ref` line, or an unexpected extra path segment. - /// `reason` carries the specific discriminant for tests and `Display`. MalformedRef { ref_name: String, reason: String }, } diff --git a/cli/src/services/mutation_trace/runtime/mutation_attribution.rs b/cli/src/services/mutation_trace/runtime/mutation_attribution.rs index e45c2b9b5..467345af1 100644 --- a/cli/src/services/mutation_trace/runtime/mutation_attribution.rs +++ b/cli/src/services/mutation_trace/runtime/mutation_attribution.rs @@ -120,9 +120,6 @@ pub struct BoundedMutationAttribution { pub reconstructed_events: usize, pub gap_resets: usize, pub barrier: Option, - /// Whether an uninterrupted replay from the exact parent tree reached the - /// last loaded event. Removed lines resolve only when it did, and only in - /// paths that also reconciled with the commit tree. pub removal_replay_anchored: bool, } @@ -153,11 +150,6 @@ fn empty_attribution() -> MutationAttributionResult { } } -/// Resolves committed touched lines from bounded mutation history. -/// -/// Added lines use the existing gap-tolerant replay. Removed lines resolve only -/// through a separate, stricter replay anchored at `parent_tree`; without a -/// parent tree (root or merge commits) every removed line stays unresolved. #[allow(clippy::too_many_arguments)] pub async fn resolve_bounded_mutation_attribution( page_source: &P, @@ -270,8 +262,6 @@ fn target_logical_paths(target: &ParsedPatch) -> BTreeSet { .collect() } -/// Every path whose parent lines a committed removal can name, plus the path -/// that holds them in the commit. fn removal_parent_paths(target: &ParsedPatch) -> BTreeSet { target .files @@ -293,8 +283,6 @@ struct RemovalAnchor<'a> { paths: BTreeSet, } -/// The removal replay: it starts at the last event leaving the exact parent -/// tree and is abandoned, never reset, at the first gap or failed transition. struct RemovalReplay { anchor: usize, lineage: MutationLineage, @@ -348,11 +336,6 @@ fn advance_removal_replay( } } -/// Reconciles the removal replay with the commit tree, path by path. A path -/// keeps its removal claims only when it holds exactly its committed lines and -/// any unobserved tail between the last event and the commit left it -/// byte-identical; otherwise (for example a partially staged file) every -/// removal claim the path bears on becomes unknown. async fn settle_removal_replay( replay: Option, last_after: &TreeId, @@ -576,8 +559,6 @@ impl ProjectedLines { } } -/// Removed lines are resolved by their canonical old-side identity: the -/// file's old path and old line number, never new-file coordinates. fn removed_line_provenance( file: &PatchFileChange, removals: Option<&MutationLineage>, @@ -666,11 +647,6 @@ where } } -/// Resolves mutation attribution for the commit captured as `commit_oid`. -/// -/// Both the commit tree and its first-parent tree are resolved from that exact -/// object ID, never from a mutable `HEAD`, so a later `HEAD` move cannot -/// change which revisions removed lines are anchored to. pub(crate) async fn resolve_post_commit_mutation_attribution( repository_root: &Path, db: &mut RepositoryAgentTraceDb, diff --git a/cli/src/services/mutation_trace/runtime/mutation_attribution/tests.rs b/cli/src/services/mutation_trace/runtime/mutation_attribution/tests.rs index 5a94b80be..f150d63f7 100644 --- a/cli/src/services/mutation_trace/runtime/mutation_attribution/tests.rs +++ b/cli/src/services/mutation_trace/runtime/mutation_attribution/tests.rs @@ -108,7 +108,6 @@ impl TreeRepo { TreeId(self.git(&["write-tree"])) } - /// Commits whatever `tree` last staged and returns the commit OID. fn commit(&self, message: &str) -> String { self.git(&[ "-c", diff --git a/cli/src/services/mutation_trace/store.rs b/cli/src/services/mutation_trace/store.rs index 94009069c..e5a181730 100644 --- a/cli/src/services/mutation_trace/store.rs +++ b/cli/src/services/mutation_trace/store.rs @@ -1,13 +1,3 @@ -//! Domain<->SQL codecs and bounded read access for the mutation-cursor -//! persistence layer. -//! -//! The codecs are the only translation between `super::types` domain values -//! and the `TEXT`/`BLOB` representations `cli/migrations/agent-trace- -//! repository/004_mutation_trace_protocol.sql` constrains those columns to. -//! Every codec here is an explicit function over a fixed set of variants — no -//! codec derives from `Debug` or a serde representation, so a variant rename -//! cannot silently change the durable encoding. - use std::collections::{BTreeMap, BTreeSet}; use anyhow::{bail, Context, Result}; @@ -21,15 +11,10 @@ use super::types::{ ScopeId, ScopeState, ScopeStatus, TreeId, WorktreeId, WorktreeState, }; -/// Encodes a worktree/event revision as the 8-byte big-endian `BLOB` stored -/// by every `revision` column in migration `004`. pub fn encode_revision(revision: u64) -> [u8; 8] { revision.to_be_bytes() } -/// Decodes a worktree/event revision from the 8-byte big-endian `BLOB` -/// migration `004`'s `CHECK (typeof(revision) = 'blob' AND length(revision) -/// = 8)` constraint guarantees on every stored value. pub fn decode_revision(blob: &[u8]) -> Result { let bytes: [u8; 8] = blob.try_into().map_err(|_| { anyhow::anyhow!("revision blob must be exactly 8 bytes, got {}", blob.len()) @@ -37,8 +22,6 @@ pub fn decode_revision(blob: &[u8]) -> Result { Ok(u64::from_be_bytes(bytes)) } -/// Encodes an [`ActorKind`] as the `mutation_trace_scopes.actor_kind` `TEXT` -/// value migration `004`'s `CHECK (actor_kind IN (...))` allow-list expects. pub fn encode_actor_kind(actor_kind: ActorKind) -> &'static str { match actor_kind { ActorKind::ClaudeCode => "claude_code", @@ -48,7 +31,6 @@ pub fn encode_actor_kind(actor_kind: ActorKind) -> &'static str { } } -/// Decodes an [`ActorKind`] from `mutation_trace_scopes.actor_kind`. pub fn decode_actor_kind(value: &str) -> Result { match value { "claude_code" => Ok(ActorKind::ClaudeCode), @@ -59,9 +41,6 @@ pub fn decode_actor_kind(value: &str) -> Result { } } -/// Encodes a [`FailureKind`] as the `failure_kind` `TEXT` value migration -/// `003` constrains `mutation_trace_worktrees.failure_kind` and -/// `mutation_trace_events.failure_kind` to. pub fn encode_failure_kind(failure_kind: FailureKind) -> &'static str { match failure_kind { FailureKind::Healthy => "healthy", @@ -69,7 +48,6 @@ pub fn encode_failure_kind(failure_kind: FailureKind) -> &'static str { } } -/// Decodes a [`FailureKind`] from a `failure_kind` column. pub fn decode_failure_kind(value: &str) -> Result { match value { "healthy" => Ok(FailureKind::Healthy), @@ -78,8 +56,6 @@ pub fn decode_failure_kind(value: &str) -> Result { } } -/// Encodes a [`ScopeStatus`] as the `mutation_trace_scopes.status` `TEXT` -/// value migration `004`'s `CHECK (status IN (...))` allow-list expects. pub fn encode_scope_status(status: ScopeStatus) -> &'static str { match status { ScopeStatus::NeverSeen => "never_seen", @@ -89,7 +65,6 @@ pub fn encode_scope_status(status: ScopeStatus) -> &'static str { } } -/// Decodes a [`ScopeStatus`] from `mutation_trace_scopes.status`. pub fn decode_scope_status(value: &str) -> Result { match value { "never_seen" => Ok(ScopeStatus::NeverSeen), @@ -100,10 +75,6 @@ pub fn decode_scope_status(value: &str) -> Result { } } -/// [`Attribution`]'s discriminant, decoupled from its `AiExclusive` payload -/// (`ScopeId`). Reconstructing a full [`Attribution`] from a persisted row -/// also needs `attribution_scope_id`, which is a `mutation_trace_events` -/// query concern owned by a later task, not by this codec. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum AttributionKind { IneligibleUnscoped, @@ -111,14 +82,8 @@ pub enum AttributionKind { AiContended, } -/// Maximum number of mutation-event rows returned by one attribution-history -/// page request. pub const MUTATION_ATTRIBUTION_PAGE_SIZE: usize = 32; -/// The cold-path subset of a historical mutation event needed by attribution. -/// -/// This deliberately omits boundary data and active scopes: attribution only -/// needs the tree transition and the event's health/attribution state. #[derive(Clone, Debug, Eq, PartialEq)] pub struct MutationEventPageRow { pub revision: u64, @@ -136,7 +101,6 @@ pub struct MutationEventTrees { pub after_tree: TreeId, } -/// The discriminant of an [`Attribution`] value. pub fn attribution_kind(attribution: &Attribution) -> AttributionKind { match attribution { Attribution::IneligibleUnscoped => AttributionKind::IneligibleUnscoped, @@ -145,9 +109,6 @@ pub fn attribution_kind(attribution: &Attribution) -> AttributionKind { } } -/// Encodes an [`AttributionKind`] as the -/// `mutation_trace_events.attribution_kind` `TEXT` value migration `004`'s -/// `CHECK (attribution_kind IN (...))` allow-list expects. pub fn encode_attribution_kind(kind: AttributionKind) -> &'static str { match kind { AttributionKind::IneligibleUnscoped => "ineligible_unscoped", @@ -156,7 +117,6 @@ pub fn encode_attribution_kind(kind: AttributionKind) -> &'static str { } } -/// Decodes an [`AttributionKind`] from `mutation_trace_events.attribution_kind`. pub fn decode_attribution_kind(value: &str) -> Result { match value { "ineligible_unscoped" => Ok(AttributionKind::IneligibleUnscoped), @@ -166,11 +126,6 @@ pub fn decode_attribution_kind(value: &str) -> Result { } } -/// [`Boundary`]'s discriminant, decoupled from its `scope`/`event`/`worktree` -/// payload. Reconstructing a full [`Boundary`] from a persisted row also -/// needs `boundary_scope_id`/`boundary_event_id`, which is a -/// `mutation_trace_events` query concern owned by a later task, not by this -/// codec. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum BoundaryKind { Start, @@ -179,7 +134,6 @@ pub enum BoundaryKind { Flush, } -/// The discriminant of a [`Boundary`] value. pub fn boundary_kind(boundary: &Boundary) -> BoundaryKind { match boundary { Boundary::Start { .. } => BoundaryKind::Start, @@ -189,9 +143,6 @@ pub fn boundary_kind(boundary: &Boundary) -> BoundaryKind { } } -/// Encodes a [`BoundaryKind`] as the `mutation_trace_events.boundary_kind` -/// `TEXT` value migration `004`'s `CHECK (boundary_kind IN (...))` -/// allow-list expects. pub fn encode_boundary_kind(kind: BoundaryKind) -> &'static str { match kind { BoundaryKind::Start => "start", @@ -201,7 +152,6 @@ pub fn encode_boundary_kind(kind: BoundaryKind) -> &'static str { } } -/// Decodes a [`BoundaryKind`] from `mutation_trace_events.boundary_kind`. #[allow( dead_code, reason = "single-event loader has no production reader; attribution history uses load_mutation_event_page" @@ -297,15 +247,10 @@ const SELECT_ALL_TREE_ROOTS_SQL: &str = "SELECT cursor_tree AS tree FROM mutatio SELECT before_tree AS tree FROM mutation_trace_events UNION SELECT after_tree AS tree FROM mutation_trace_events"; -/// Idle-insert: only takes effect when `worktree_id` has no row yet, so an -/// existing worktree's cursor/revision/failure state is never overwritten. const INSERT_WORKTREE_IF_ABSENT_SQL: &str = "INSERT INTO mutation_trace_worktrees (worktree_id, cursor_tree, revision, tainted, failure_kind, needs_rebaseline) VALUES (?1, ?2, ?3, 0, 'healthy', 0) ON CONFLICT (worktree_id) DO NOTHING"; -/// Idle-insert: only takes effect when `scope_id` has no row yet, so an -/// existing scope's worktree/actor/status is never overwritten. The caller -/// re-reads the row afterward to detect a worktree/actor mismatch. const INSERT_SCOPE_IF_ABSENT_SQL: &str = "INSERT INTO mutation_trace_scopes (scope_id, worktree_id, actor_kind, status) VALUES (?1, ?2, ?3, 'never_seen') @@ -330,17 +275,6 @@ const INSERT_MUTATION_EVENT_SQL: &str = "INSERT INTO mutation_trace_events const INSERT_MUTATION_EVENT_ACTIVE_SCOPE_SQL: &str = "INSERT INTO mutation_trace_event_active_scopes (worktree_id, revision, scope_id) VALUES (?1, ?2, ?3)"; -/// Bounded runtime projection of one worktree's durable protocol state, -/// loaded by [`MutationTraceStore::load_worktree`]. Scoped to that worktree's -/// currently `Active` scopes plus, when present, the scope `load_worktree` -/// was explicitly asked about (regardless of its status) — never every -/// historical scope, and never a `mutation_trace_events` row. -/// -/// `attempts`, `mutation_events`, and `external_taint` are always empty: -/// `AttemptState` is transient and never persisted, historical -/// `MutationEvent`s are a cold-path concern -/// ([`MutationTraceStore::load_mutation_event`]), and `external_taint` is -/// never DB-authoritative (see the plan's non-goals). #[derive(Clone, Debug, Eq, PartialEq)] pub struct WorktreeProjection { pub worktree_id: WorktreeId, @@ -350,10 +284,6 @@ pub struct WorktreeProjection { } impl WorktreeProjection { - /// Widens this bounded projection into a full [`ProtocolState`] so pure - /// `protocol.rs` functions can operate on it unchanged. `worktrees` - /// carries only the one loaded worktree; `attempts`, `mutation_events`, - /// and `external_taint` are always empty. pub fn into_protocol_state(self) -> ProtocolState { let mut worktrees = BTreeMap::new(); worktrees.insert(self.worktree_id, self.worktree_state); @@ -572,10 +502,6 @@ impl<'a> MutationTraceStore<'a> { Self { db } } - /// Idempotently initializes `worktree`'s durable cursor row: `revision=0`, - /// healthy, not tainted, not needing rebaseline, with `cursor_tree` set to - /// `initial_tree`. A no-op when the worktree row already exists — an - /// existing cursor, revision, or failure state is never overwritten. pub async fn initialize_worktree( &self, worktree: &WorktreeId, @@ -595,21 +521,6 @@ impl<'a> MutationTraceStore<'a> { Ok(()) } - /// Idempotently registers `scope` as belonging to `worktree` and - /// `actor_kind`. Inserts a new `NeverSeen` row when `scope` has none yet. - /// When a row already exists, returns its current state unchanged as long - /// as its `worktree_id` and `actor_kind` agree with the arguments — this - /// never resurrects a terminal scope or changes its status — and returns - /// `Err` when either disagrees, since a scope's worktree and actor are - /// permanent facts fixed at first registration. - /// - /// `worktree` must already have a durable `mutation_trace_worktrees` row - /// (via [`MutationTraceStore::initialize_worktree`]), checked before any - /// scope row is inserted or read back — this never auto-creates the - /// worktree. This applies identically to a fresh `scope` and to an - /// existing one: an existing scope whose stored `worktree_id` has no - /// worktree row is never returned as valid merely because it matches the - /// arguments. pub async fn register_scope( &self, scope: &ScopeId, @@ -654,27 +565,6 @@ impl<'a> MutationTraceStore<'a> { Ok(scope_state) } - /// Loads a bounded projection of `worktree`'s durable protocol state, or - /// `None` when the worktree does not exist. - /// - /// `scope` and `event_key.scope_id` are two ways of naming the same - /// operation-local scope identity: when both are supplied they must - /// agree, or this returns `Err` before loading or querying anything. - /// Otherwise the supplied `scope`, or `event_key.scope_id` when only - /// `event_key` is supplied, becomes the effective referenced scope: a - /// durable `mutation_trace_scopes` row for it must exist, or this returns - /// `Err` — a missing effective scope is never silently omitted from the - /// projection. When it exists it is loaded and included in the - /// projection regardless of its status, and this returns `Err` if it - /// belongs to a worktree other than the one requested. Both checks run - /// before the `processed_events` replay lookup, so an orphan - /// `mutation_trace_processed_events` row can never enter the projection - /// without its owning scope. The projection's `scopes` otherwise contains - /// only this worktree's currently `Active` scopes. `processed_events` - /// contains `event_key` only when a matching `(scope_id, event_id)` row - /// already exists; the lookup never references a `worktree_id` column, - /// since `mutation_trace_processed_events` has none. This method never - /// queries `mutation_trace_events`. pub async fn load_worktree( &self, worktree: &WorktreeId, @@ -725,10 +615,6 @@ impl<'a> MutationTraceStore<'a> { })) } - /// Reconstructs one historical [`MutationEvent`] for `(worktree, - /// revision)`, decoding its full `Attribution` and `Boundary`, or `None` - /// when no such row exists. Never called from `load_worktree` or from - /// any hook-boundary path. #[allow( dead_code, reason = "single-event loader has no production reader; attribution history uses load_mutation_event_page" @@ -775,14 +661,6 @@ impl<'a> MutationTraceStore<'a> { })) } - /// Reads one descending page of the historical mutation events for exactly - /// `worktree`. When `revision_cursor` is present, only revisions strictly - /// below it are returned, so the caller can continue from the last row of - /// a prior page without duplicates. The requested limit is always capped - /// at [`MUTATION_ATTRIBUTION_PAGE_SIZE`]. - /// - /// This is a read-only cold path. It does not load active scopes, processed - /// events, boundary data, or any timestamp column. pub async fn load_mutation_event_page( &self, worktree: &WorktreeId, @@ -960,24 +838,6 @@ impl<'a> MutationTraceStore<'a> { Ok(rows.into_iter().collect()) } - /// Loads the durable [`ScopeState`] for `scope_id` — its status, - /// `actor_kind`, and `worktree_id` — or `None` when no - /// `mutation_trace_scopes` row exists for it. - /// - /// A cold-path single-row read, and deliberately the narrowest scope seam - /// there is: it reads one `mutation_trace_scopes` row and nothing else. It - /// never consults `mutation_trace_events`, - /// `mutation_trace_processed_events`, or the scope's - /// `mutation_trace_worktrees` row, and it must not widen into a - /// projection — [`MutationTraceStore::load_worktree`] is the projection - /// seam, and a caller needing worktree state alongside a scope belongs - /// there instead. - /// - /// This never adjudicates worktree identity: a scope whose `worktree_id` - /// differs from the caller's own worktree is returned as-is, not rejected. - /// Comparing the two is the caller's decision, since the same row is a - /// legitimate read from its owning worktree and a cross-worktree reference - /// from any other. pub async fn load_scope(&self, scope_id: &ScopeId) -> Result> { let rows = self .db @@ -1242,11 +1102,6 @@ fn boundary_payload(boundary: &Boundary) -> (Option<&str>, Option<&str>) { } } -/// Derives the single effective referenced scope from `scope` and -/// `event_key`, per the four-case definition in the -/// `mutation-cursor-store-persistence` plan's T03: `None` when neither is -/// supplied; the supplied one when only one is; the agreeing identity when -/// both are supplied and equal; `Err` when both are supplied and disagree. fn effective_referenced_scope<'k>( scope: Option<&'k ScopeId>, event_key: Option<&'k EventKey>, @@ -1406,9 +1261,6 @@ fn mutation_event_page_row_from_turso(row: &turso::Row) -> Result BTreeMap { ]) } -/// Prepares and immediately commits `attempt` against `boundary`, the shape -/// every state-sequence test below chains repeatedly. fn prepare_and_commit( state: &ProtocolState, attempt: &AttemptId, @@ -831,8 +829,6 @@ fn commit_emits_exactly_one_mutation_event_with_correct_attribution_boundary_and scope_with_status(ScopeStatus::Active, worktree("wt0")), ); - // Advance never changes the scope set, so the pre- and post-transition - // live scopes are identical: attribution is unambiguously AiExclusive. let prepared = prepare( &state, attempt_id("attempt0"), @@ -1929,10 +1925,6 @@ fn recover_is_a_no_op_for_blocked_preconditions() { } } -// T07: cross-action state-sequence tests. Each of the eight scenarios below -// is required by the plan; none is a single-action test already covered by -// T01-T06. - #[test] fn attribution_transitions_from_contended_to_exclusive_across_a_close_boundary() { let mut state = ProtocolState::default(); @@ -1948,7 +1940,6 @@ fn attribution_transitions_from_contended_to_exclusive_across_a_close_boundary() scope_with_status(ScopeStatus::Active, worktree("wt0")), ); - // Both scopes are live: an Advance observing a real change is AiContended. let step_a = prepare_and_commit( &state, &attempt_id("attempt_a"), @@ -1971,9 +1962,6 @@ fn attribution_transitions_from_contended_to_exclusive_across_a_close_boundary() BTreeSet::from([scope("scope0"), scope("scope1")]) ); - // Close also observes a change; because commitAttempt computes live - // scopes *before* nextScope closes scope0, this still emits AiContended, - // not AiExclusive. let step_b = prepare_and_commit( &step_a.state, &attempt_id("attempt_b"), @@ -2000,8 +1988,6 @@ fn attribution_transitions_from_contended_to_exclusive_across_a_close_boundary() BTreeSet::from([scope("scope0"), scope("scope1")]) ); - // Now only scope1 is live: the next observed change is where AiExclusive - // first appears. let step_c = prepare_and_commit( &step_b.state, &attempt_id("attempt_c"), @@ -2137,9 +2123,6 @@ fn replay_of_a_committed_event_key_is_rejected_without_mutating_state() { ); assert!(first.evaluation.accepted); - // The CAS baseline is fresh (matches the post-commit worktree state); - // only the replayed EventKey (scope0/event0, same as `start_boundary`) - // should cause rejection. let before = first.state.clone(); let replay = prepare_and_commit( &first.state, @@ -2175,7 +2158,6 @@ fn stale_attempt_prepared_before_an_intervening_flush_commit_is_rejected_without scope_with_status(ScopeStatus::NeverSeen, worktree("wt0")), ); - // Prepare the eventual stale attempt first, baselined at revision 0. let prepared_stale = prepare( &state, attempt_id("attempt_stale"), @@ -2183,8 +2165,6 @@ fn stale_attempt_prepared_before_an_intervening_flush_commit_is_rejected_without tree("tree_target"), ); - // An unrelated Flush commits and advances the worktree before the - // prepared attempt above is ever committed. let intervened = prepare_and_commit( &prepared_stale, &attempt_id("attempt_flush"), @@ -2229,7 +2209,6 @@ fn competing_prepared_attempts_the_second_to_commit_is_rejected_by_cas() { .worktrees .insert(worktree("wt0"), healthy_worktree(tree("tree0"), 0)); - // Both A and B are prepared against the same revision-0 baseline. let prepared_a = prepare( &state, attempt_id("attempt_a"), @@ -2312,10 +2291,6 @@ fn taint_invalidates_a_prepared_attempt_via_stale_revision() { ); } -// T07: invariant-style tests, named to mirror the Quint invariants this -// module refines. Each reaches its precondition through real transitions -// rather than a manually constructed state, per the task's own requirement. - #[test] fn scope_started_at_most_once_and_stays_terminal_after_a_real_close() { let mut state = ProtocolState::default(); @@ -2338,9 +2313,6 @@ fn scope_started_at_most_once_and_stays_terminal_after_a_real_close() { ScopeStatus::Active ); - // ScopeStartedAtMostOnce: a second Start (fresh EventKey) on an - // already-Active scope is accepted-but-non-observing and does not - // re-run activation. let restarted = prepare_and_commit( &started.state, &attempt_id("attempt_restart"), @@ -2381,8 +2353,6 @@ fn scope_started_at_most_once_and_stays_terminal_after_a_real_close() { ScopeStatus::Closed ); - // TerminalScopesStayTerminal: a Start against the now-Closed scope - // cannot reactivate it. let reopen_attempt = prepare_and_commit( &closed.state, &attempt_id("attempt_reopen"), @@ -2528,8 +2498,6 @@ fn rejected_attempts_do_not_commit_evidence_across_a_mixed_accept_reject_sequenc AttemptStatus::Rejected ); - // RejectedAttemptsDoNotCommitEvidence: the rejected Advance must not have - // added any mutation evidence beyond what the accepted Start produced. assert_eq!( rejected.state.mutation_events, accepted.state.mutation_events @@ -2537,10 +2505,6 @@ fn rejected_attempts_do_not_commit_evidence_across_a_mixed_accept_reject_sequenc assert_eq!(rejected.state.mutation_events.len(), 1); } -// T07 post-review correction: `needsRebaseline` must suppress mutation -// evidence even when `commit` genuinely observes a real tree change -// (`MutationEventsCrossOnlyTrustworthyProtocolStates`). - #[test] fn needs_rebaseline_suppresses_mutation_event_even_when_commit_observes_a_real_tree_change() { let mut state = ProtocolState::default(); @@ -2590,16 +2554,6 @@ fn needs_rebaseline_suppresses_mutation_event_even_when_commit_observes_a_real_t ); } -// T07 post-review correction: Quint's `revision: int` is unbounded; this -// refinement's `revision: u64` is not, so every revision-advancing action -// must refuse to wrap past `u64::MAX` rather than commit partial or wrapped -// state. - -// A commit that would advance revision is rejected at `u64::MAX`: headroom -// is required for advancement, not for acceptance in general. Paired with -// `no_change_flush_commits_at_u64_max_without_advancing_revision` below, -// which proves the other half — a commit that would NOT advance revision -// (a no-change `Flush`) is accepted at `u64::MAX`. #[test] fn commit_that_would_advance_is_rejected_at_u64_max() { let mut state = ProtocolState::default(); @@ -2648,12 +2602,6 @@ fn commit_that_would_advance_is_rejected_at_u64_max() { ); } -// T07 post-review correction: the first checked-u64 guard required revision -// headroom for every accepted commit, even a no-change `Flush` that would -// not advance revision. Quint's `commitAttempt` accepts and commits that -// case without advancing revision, so a fresh no-change `Flush` at -// `revision: u64::MAX` must commit successfully rather than being rejected -// for headroom it does not need. #[test] fn no_change_flush_commits_at_u64_max_without_advancing_revision() { let mut state = ProtocolState::default(); diff --git a/cli/src/services/mutation_trace/types.rs b/cli/src/services/mutation_trace/types.rs index 7ec4584e1..5886b09c3 100644 --- a/cli/src/services/mutation_trace/types.rs +++ b/cli/src/services/mutation_trace/types.rs @@ -1,45 +1,24 @@ -//! Pure domain types for the mutation-cursor protocol. -//! -//! Refines `spec/mutation_cursor.qnt:2-117` (state types) and -//! `spec/mutation_cursor.qnt:151-245` (pure accessors). The Quint model uses -//! finite enumerated identities (`WT0`/`Scope0`/...) as bounded verification -//! domains only; `spec/mutation_cursor.md` states production code "must -//! support larger and unbounded identifier spaces". This module therefore -//! refines every identity type as an opaque wrapper over an owned string -//! rather than a fixed enum, and carries no Git/DB/filesystem/environment/ -//! network/lock/async dependency. - -/// Durable identity of a worktree. Refines `WorktreeId` (`spec/mutation_cursor.qnt:2`). #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct WorktreeId(pub String); -/// Durable identity of an AI scope/session. Refines `ScopeId` (`spec/mutation_cursor.qnt:4`). #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct ScopeId(pub String); -/// Identity of a captured worktree tree snapshot. Refines `TreeId` (`spec/mutation_cursor.qnt:5`). #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct TreeId(pub String); -/// Identity of a hook delivery event. Refines `EventId` (`spec/mutation_cursor.qnt:6-17`). #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct EventId(pub String); -/// Identity of a speculative attempt. Refines `AttemptId` (`spec/mutation_cursor.qnt:17`). #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct AttemptId(pub String); -/// Replay/idempotency identity for a hook delivery, scoped by `ScopeId` and -/// `EventId`. Refines `EventKey` (`spec/mutation_cursor.qnt:18-21`). #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct EventKey { pub scope_id: ScopeId, pub event_id: EventId, } -/// The harness that owns a scope. Unlike the identity types above, this is a -/// real closed set (every supported harness), not a bounded verification -/// domain, so it stays a fixed enum. Refines `ActorKind` (`spec/mutation_cursor.qnt:3`). #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum ActorKind { ClaudeCode, @@ -48,14 +27,12 @@ pub enum ActorKind { Pi, } -/// Snapshot-failure state of a worktree. Refines `FailureKind` (`spec/mutation_cursor.qnt:22`). #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)] pub enum FailureKind { Healthy, SnapshotFailure, } -/// Lifecycle status of a scope. Refines `ScopeStatus` (`spec/mutation_cursor.qnt:24`). #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum ScopeStatus { NeverSeen, @@ -64,7 +41,6 @@ pub enum ScopeStatus { Abandoned, } -/// Lifecycle status of a speculative attempt. Refines `AttemptStatus` (`spec/mutation_cursor.qnt:25`). #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum AttemptStatus { Available, @@ -73,8 +49,6 @@ pub enum AttemptStatus { Rejected, } -/// Mutation-evidence attribution for a worktree. Refines `Attribution` -/// (`spec/mutation_cursor.qnt:26-29`). #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)] pub enum Attribution { IneligibleUnscoped, @@ -82,18 +56,6 @@ pub enum Attribution { AiContended, } -/// A hook or flush boundary at which the protocol may transition state. -/// Refines `Boundary` (`spec/mutation_cursor.qnt:31-35`), field-for-field: -/// `Start`/`Advance`/`Close` carry only `scope`/`event`, exactly like the -/// Quint constructors, and `Flush` carries only `worktree`. -/// -/// A hook variant deliberately carries no independent `worktree` field. The -/// Quint model's `boundaryWorktree` never stores a worktree either — it -/// derives one from `scopeWorktree(data.scope)`. Storing a worktree directly -/// on the boundary would let a value claim a worktree inconsistent with its -/// own scope's true (durable, assigned-for-life) worktree, a state the -/// Quint type cannot represent. See [`boundary_worktree`] for how this -/// refinement resolves a hook boundary's worktree without that field. #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)] pub enum Boundary { Start { scope: ScopeId, event: EventId }, @@ -102,8 +64,6 @@ pub enum Boundary { Flush { worktree: WorktreeId }, } -/// Durable per-worktree cursor and failure state. Refines `WorktreeState` -/// (`spec/mutation_cursor.qnt:37-43`). #[derive(Clone, Debug, Eq, PartialEq)] pub struct WorktreeState { pub cursor_tree: TreeId, @@ -113,7 +73,6 @@ pub struct WorktreeState { pub needs_rebaseline: bool, } -/// Durable per-scope lifecycle state. Refines `ScopeState` (`spec/mutation_cursor.qnt:45-49`). #[derive(Clone, Debug, Eq, PartialEq)] pub struct ScopeState { pub status: ScopeStatus, @@ -121,7 +80,6 @@ pub struct ScopeState { pub worktree_id: WorktreeId, } -/// Transient speculative-attempt state. Refines `AttemptState` (`spec/mutation_cursor.qnt:51-57`). #[derive(Clone, Debug, Eq, PartialEq)] pub struct AttemptState { pub status: AttemptStatus, @@ -131,8 +89,6 @@ pub struct AttemptState { pub after_tree: TreeId, } -/// Durable mutation evidence emitted by a committed attempt. Refines -/// `MutationEvent` (`spec/mutation_cursor.qnt:99-109`). #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)] pub struct MutationEvent { pub worktree_id: WorktreeId, @@ -146,51 +102,20 @@ pub struct MutationEvent { pub boundary: Boundary, } -/// A scope is eligible to contribute to attribution. Refines `isLive` -/// (`spec/mutation_cursor.qnt:167`). pub fn is_live(status: ScopeStatus) -> bool { status == ScopeStatus::Active } impl ScopeState { - /// The worktree this scope belongs to. Refines `scopeWorktree` - /// (`spec/mutation_cursor.qnt:151-157`). - /// - /// The Quint function is a pure `match` over `ScopeId` only because the - /// model's identity enum has a fixed, static worktree partition - /// (`Scope0`/`Scope1`/`Scope2` always belong to `WT0`, `Scope3` always to - /// `WT1`). This refinement's `ScopeId` is an opaque, dynamically created - /// identifier with no such static partition (see the module doc - /// comment), so the only faithful source for a scope's worktree is its - /// own durable state — the same fact the Quint model also carries on - /// `ScopeState.worktreeId`, kept consistent with the static function by - /// construction at scope-creation time. pub fn scope_worktree(&self) -> WorktreeId { self.worktree_id.clone() } - /// Refines `isLive` applied to this scope's status. pub fn is_live(&self) -> bool { is_live(self.status) } } -/// The worktree a boundary applies to. Refines `boundaryWorktree` -/// (`spec/mutation_cursor.qnt:172-178`). -/// -/// For `Start`/`Advance`/`Close`, the function reads the `ScopeId` from the -/// boundary and resolves that exact key in the supplied protocol scope -/// state, mirroring how the Quint function derives the result from -/// `scopeWorktree(data.scope)` rather than from an independently stored -/// value (see the [`Boundary`] doc comment). It does not accept an arbitrary -/// `ScopeState` alongside the boundary: the boundary's own `ScopeId` is the -/// only key ever used to look one up, so no caller can supply a worktree -/// inconsistent with the boundary's scope. The result is `None` when that -/// key is absent from `scopes` (for example, an unknown or not-yet-created -/// scope). -/// -/// For `Flush`, the worktree is carried directly by the boundary and -/// `scopes` is not consulted. pub fn boundary_worktree( boundary: &Boundary, scopes: &std::collections::BTreeMap, @@ -203,9 +128,6 @@ pub fn boundary_worktree( } } -/// The scope a boundary applies to, or `None` for a `Flush` boundary, which -/// carries no scope. Refines `boundaryScope` (`spec/mutation_cursor.qnt:180-186`); -/// `None` replaces the Quint model's arbitrary `Scope0` placeholder default. pub fn boundary_scope(boundary: &Boundary) -> Option { match boundary { Boundary::Start { scope, .. } @@ -215,9 +137,6 @@ pub fn boundary_scope(boundary: &Boundary) -> Option { } } -/// The event a boundary applies to, or `None` for a `Flush` boundary, which -/// carries no event. Refines `boundaryEvent` (`spec/mutation_cursor.qnt:188-194`); -/// `None` replaces the Quint model's arbitrary `Event0` placeholder default. pub fn boundary_event(boundary: &Boundary) -> Option { match boundary { Boundary::Start { event, .. } @@ -227,8 +146,6 @@ pub fn boundary_event(boundary: &Boundary) -> Option { } } -/// The replay identity of a boundary, or `None` for a `Flush` boundary. -/// Refines `boundaryEventKey` (`spec/mutation_cursor.qnt:196-202`). pub fn boundary_event_key(boundary: &Boundary) -> Option { match (boundary_scope(boundary), boundary_event(boundary)) { (Some(scope_id), Some(event_id)) => Some(EventKey { scope_id, event_id }), @@ -236,41 +153,26 @@ pub fn boundary_event_key(boundary: &Boundary) -> Option { } } -/// A boundary is a hook delivery (`Start`/`Advance`/`Close`), not a `Flush`. -/// Refines `isHook` (`spec/mutation_cursor.qnt:204-210`). pub fn is_hook(boundary: &Boundary) -> bool { !matches!(boundary, Boundary::Flush { .. }) } -/// Refines `isStart` (`spec/mutation_cursor.qnt:212-216`). pub fn is_start(boundary: &Boundary) -> bool { matches!(boundary, Boundary::Start { .. }) } -/// Refines `isAdvance` (`spec/mutation_cursor.qnt:218-222`). pub fn is_advance(boundary: &Boundary) -> bool { matches!(boundary, Boundary::Advance { .. }) } -/// Refines `isClose` (`spec/mutation_cursor.qnt:224-228`). pub fn is_close(boundary: &Boundary) -> bool { matches!(boundary, Boundary::Close { .. }) } -/// Refines `isFlush` (`spec/mutation_cursor.qnt:230-234`). pub fn is_flush(boundary: &Boundary) -> bool { matches!(boundary, Boundary::Flush { .. }) } -/// The protocol's full durable-plus-transient state. Refines the top-level -/// state variables `worktrees`/`scopes`/`externalTaint`/`processedEvents`/ -/// `attempts`/`mutationEvents` (`spec/mutation_cursor.qnt:2-14`). -/// -/// Quint's verification-only histories (`cursorHistory`, `protocolHistory`, -/// `scopeHistory`, `abandonHistory`, `startHistory`, `recoveryHistory`, -/// `taintHistory`, `evidenceAttempts`, `scopeStartCount`, `everTerminal`) are -/// not represented here; they exist only to state invariants over the -/// verified spec and have no role in the protocol's own behavior. #[derive(Clone, Debug, Default, Eq, PartialEq)] pub struct ProtocolState { pub worktrees: std::collections::BTreeMap, diff --git a/cli/src/services/patch.rs b/cli/src/services/patch.rs index 2a85d7e93..8b0f37c63 100644 --- a/cli/src/services/patch.rs +++ b/cli/src/services/patch.rs @@ -1,19 +1,3 @@ -//! Patch domain model and parser for in-memory parsed patch representation. -//! -//! This module defines the core types for representing parsed unified-diff -//! patches as structured data, capturing only touched lines (added/removed) -//! plus the minimal per-file/per-hunk metadata needed to interpret them. -//! -//! Non-hunk headers and unchanged context lines are intentionally excluded. -//! -//! The types are `serde`-serializable and deserializable so they can round-trip -//! through a structured representation (e.g., JSON) and be loaded back into -//! the same struct shape. -//! -//! The parser supports both `Index:` (SVN-style) and `diff --git` (git-style) -//! unified-diff formats and produces deterministic `ParsedPatch` structs from -//! raw patch text. - use serde::{Deserialize, Serialize}; mod git_path; @@ -24,80 +8,52 @@ const GIT_SOURCE_PREFIX: &str = "a/"; const GIT_DESTINATION_PREFIX: &str = "b/"; const DEV_NULL: &str = "/dev/null"; -/// Top-level parsed patch containing one or more file changes. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] pub struct ParsedPatch { pub files: Vec, } -/// A single file's changes within a patch. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] pub struct PatchFileChange { - /// Path of the file before the change. Empty string for new files. pub old_path: String, - /// Path of the file after the change. Empty string for deleted files. pub new_path: String, - /// Kind of file change. pub kind: FileChangeKind, - /// Hunks within this file change. pub hunks: Vec, } -/// Kind of change applied to a file. #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub enum FileChangeKind { - /// File was newly created. Added, - /// File was modified in place. Modified, - /// File was deleted. Deleted, - /// File was renamed (path changed, content may or may not have changed). Renamed, } -/// A single hunk within a file change, containing touched lines. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] pub struct PatchHunk { - /// Starting line number in the old file (0 for new-file hunks). pub old_start: u64, - /// Number of lines in the old file context for this hunk (0 for new-file hunks). pub old_count: u64, - /// Starting line number in the new file (0 for deleted-file hunks). pub new_start: u64, - /// Number of lines in the new file context for this hunk (0 for deleted-file hunks). pub new_count: u64, - /// Optional model provenance associated with this hunk. #[serde(default)] pub model_id: Option, - /// Touched lines within this hunk (added and removed lines only; - /// unchanged context lines are excluded). pub lines: Vec, } -/// A single touched line within a hunk. #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] pub struct TouchedLine { - /// Kind of line change. pub kind: TouchedLineKind, - /// Line number in the new file for added lines, or in the old file - /// for removed lines. pub line_number: u64, - /// Content of the line (without the leading `+`/`-` prefix). pub content: String, - /// Optional session identifier associated with this touched line. #[serde(default)] pub session_id: Option, } -/// Kind of touched line. #[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub enum TouchedLineKind { - /// Line was added. Added, - /// Line was removed. Removed, } @@ -114,12 +70,6 @@ impl std::fmt::Display for ParseError { impl std::error::Error for ParseError {} -/// Error produced when loading a `ParsedPatch` from serialized JSON fails. -/// -/// `PatchLoadError` carries an actionable message describing why the JSON -/// payload could not be reconstructed into a valid `ParsedPatch`. Common -/// causes include malformed JSON syntax, missing required fields, or type -/// mismatches in the serialized structure. #[derive(Clone, Debug, Eq, PartialEq)] pub struct PatchLoadError { pub message: String, @@ -133,34 +83,12 @@ impl std::fmt::Display for PatchLoadError { impl std::error::Error for PatchLoadError {} -/// Load a `ParsedPatch` from a JSON string previously produced by -/// serializing a `ParsedPatch`. -/// -/// This is the primary storage-agnostic entrypoint for reconstructing a -/// parsed patch from serialized JSON content. Callers who have already read -/// the JSON from a database, file, or any other source can pass the string -/// directly. -/// -/// # Errors -/// -/// Returns `PatchLoadError` with an actionable message when the input is -/// not valid JSON or does not match the expected `ParsedPatch` structure. pub fn load_patch_from_json(input: &str) -> Result { serde_json::from_str(input).map_err(|e| PatchLoadError { message: format!("invalid patch JSON: {e}"), }) } -/// Parse raw unified-diff text into a `ParsedPatch`. -/// -/// Supports both `Index:` (SVN-style) and `diff --git` (git-style) patch -/// formats. Context lines (space-prefixed) are excluded from the output; -/// only added (`+`) and removed (`-`) lines are captured as touched lines. -/// -/// # Errors -/// -/// Returns `ParseError` with an actionable message when the input is malformed, -/// such as an invalid hunk header or a `---`/`+++` line that cannot be parsed. pub fn parse_patch(input: &str, session_id: Option<&str>) -> Result { let mut files: Vec = Vec::new(); let mut current_file: Option = None; @@ -168,9 +96,7 @@ pub fn parse_patch(input: &str, session_id: Option<&str>) -> Result) -> Result) -> Result) -> Result) -> Result) -> Result, old_path: Option, @@ -387,8 +299,6 @@ fn normalize_paths_for_kind( (old_path, new_path) } -/// Determine file change kind from old/new paths when no explicit metadata -/// was found. fn determine_file_kind(old_path: &str, new_path: &str) -> FileChangeKind { if old_path == "/dev/null" || old_path.is_empty() { FileChangeKind::Added @@ -449,8 +359,6 @@ fn path_error(line: &str, error: &GitPathError) -> ParseError { } } -/// Parse a hunk header (the part after `@@ `) and then consume hunk body lines -/// until the next file boundary or end of input. fn parse_hunk_header_and_body<'a, I>( rest: &str, lines: &mut std::iter::Peekable, @@ -459,7 +367,6 @@ fn parse_hunk_header_and_body<'a, I>( where I: Iterator, { - // Format: -old_start[,old_count] +new_start[,new_count] @@ [optional context] let header_end = rest.find("@@").ok_or_else(|| ParseError { message: format!("invalid hunk header: missing closing '@@' in {rest:?}"), })?; @@ -475,27 +382,21 @@ where let (old_start, old_count) = parse_range_part(old_range, '-')?; let (new_start, new_count) = parse_range_part(new_range, '+')?; - // Consume hunk body lines until we hit a line that starts a new file - // section or another hunk header or end of input. let mut touched_lines: Vec = Vec::new(); let mut old_line_num = old_start; let mut new_line_num = new_start; while let Some(&line) = lines.peek() { - // Stop at file boundaries if line.starts_with("diff --git ") || line.starts_with("Index: ") || line.starts_with("===") { break; } - // Stop at next hunk header if line.starts_with("@@ ") { break; } - // Stop at ---/+++ headers (next file section in Index: format) if line.starts_with("--- ") || line.starts_with("+++ ") { break; } - // Stop at git metadata lines if line.starts_with("new file mode ") || line.starts_with("deleted file mode ") || line.starts_with("old mode ") @@ -510,11 +411,9 @@ where break; } - // Consume the line let line = lines.next().unwrap(); if let Some(content) = line.strip_prefix('+') { - // Added line touched_lines.push(TouchedLine { kind: TouchedLineKind::Added, line_number: new_line_num, @@ -523,7 +422,6 @@ where }); new_line_num += 1; } else if let Some(content) = line.strip_prefix('-') { - // Removed line touched_lines.push(TouchedLine { kind: TouchedLineKind::Removed, line_number: old_line_num, @@ -531,19 +429,9 @@ where session_id: session_id.map(str::to_string), }); old_line_num += 1; - } else if line.starts_with(' ') || line.starts_with('\t') { - // Context line — skip but advance both counters - old_line_num += 1; - new_line_num += 1; - } else if line.is_empty() { - // Empty line within a hunk body — could be a context line with - // no leading space (some diffs emit this). Treat as context. + } else if line.starts_with(' ') || line.starts_with('\t') || line.is_empty() { old_line_num += 1; new_line_num += 1; - } else if line.starts_with('\\') { - // "\ No newline at end of file" — skip - } else { - // Unknown line format within hunk — skip } } @@ -557,7 +445,6 @@ where }) } -/// Parse a range part like `-3,7` or `+1,9` from a hunk header. fn parse_range_part(s: &str, prefix: char) -> Result<(u64, u64), ParseError> { let s = s.strip_prefix(prefix).unwrap_or(s).trim(); let parts: Vec<&str> = s.splitn(2, ',').collect(); diff --git a/cli/src/services/repository_identity/mod.rs b/cli/src/services/repository_identity/mod.rs index c795169d7..f515e879d 100644 --- a/cli/src/services/repository_identity/mod.rs +++ b/cli/src/services/repository_identity/mod.rs @@ -1,46 +1,22 @@ -//! Pure repository identity canonicalization and hashing. -//! -//! Turns an explicit configured identity or a Git remote URL into a -//! scheme-neutral canonical identity, then derives a stable repository ID as -//! `sha256("sce-repository-id-v1\0" + canonical_identity)` hex. -//! -//! This root module performs no I/O: it never opens databases, reads Git -//! config, or touches the filesystem. Runtime precedence resolution and Git -//! remote lookup live in [`resolve`]. Errors intentionally never echo the -//! raw input so credential-bearing remote URLs cannot leak through -//! diagnostics. - pub mod resolve; use sha2::{Digest, Sha256}; -/// Domain-separation prefix hashed before the canonical identity. pub const REPOSITORY_ID_HASH_DOMAIN: &[u8] = b"sce-repository-id-v1\0"; -/// A resolved repository identity: the safe canonical form plus its hash. #[derive(Debug, Clone, PartialEq, Eq)] pub struct RepositoryIdentity { - /// Credential-free canonical identity, safe to display and store. pub canonical_identity: String, - /// Lowercase hex SHA-256 of the domain prefix plus canonical identity. pub repository_id: String, } -/// Canonicalization failure. Variants carry no input fragments so -/// credential-bearing URLs never leak into error output. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum RepositoryIdentityError { - /// Explicit identity was empty after trimming whitespace. EmptyExplicitIdentity, - /// Remote URL was empty after trimming whitespace. EmptyRemoteUrl, - /// Remote URL scheme is not a supported Git transport. UnsupportedRemoteUrl, - /// Remote URL has no usable host component. MissingHost, - /// Remote URL has no usable repository path component. MissingPath, - /// Remote URL port component is not a valid number. InvalidPort, } @@ -62,9 +38,6 @@ impl std::fmt::Display for RepositoryIdentityError { impl std::error::Error for RepositoryIdentityError {} -/// Builds a repository identity from an explicitly configured identity -/// string (`agent_trace.repository_id`). Canonicalization is trimming only: -/// explicit identities are operator-chosen opaque values, not URLs. pub fn repository_identity_from_explicit( raw: &str, ) -> Result { @@ -75,8 +48,6 @@ pub fn repository_identity_from_explicit( Ok(identity_from_canonical(canonical.to_string())) } -/// Builds a repository identity from a Git remote URL. Equivalent SSH, -/// SCP-style, and HTTPS URLs canonicalize to the same identity. pub fn repository_identity_from_remote_url( raw: &str, ) -> Result { @@ -84,7 +55,6 @@ pub fn repository_identity_from_remote_url( Ok(identity_from_canonical(canonical)) } -/// Derives the repository ID hex digest for a canonical identity. pub fn derive_repository_id(canonical_identity: &str) -> String { let mut hasher = Sha256::new(); hasher.update(REPOSITORY_ID_HASH_DOMAIN); @@ -92,10 +62,6 @@ pub fn derive_repository_id(canonical_identity: &str) -> String { hex_encode(&hasher.finalize()) } -/// Canonicalizes a Git remote URL to the scheme-neutral form -/// `host[:port]/path` with credentials stripped, hostname lowercased, -/// default ports removed, and query/fragment/trailing-slash/trailing-`.git` -/// cleaned up. The returned string never contains credentials. pub fn canonicalize_remote_url(raw: &str) -> Result { let trimmed = raw.trim(); if trimmed.is_empty() { @@ -143,7 +109,6 @@ fn canonicalize_scheme_url(scheme: &str, rest: &str) -> Result Result { - // SCP-style form: [user@]host:path — the colon must come before any '/'. let host_port_end = input.find(':'); let first_slash = input.find('/'); let colon = match (host_port_end, first_slash) { @@ -159,7 +124,6 @@ fn canonicalize_scp_style(input: &str) -> Result &str { } fn split_host_port(host_port: &str) -> Result<(String, Option), RepositoryIdentityError> { - // IPv6 literals are bracketed: [::1]:2222 if let Some(rest) = host_port.strip_prefix('[') { let Some(close) = rest.find(']') else { return Err(RepositoryIdentityError::MissingHost); diff --git a/cli/src/services/repository_identity/resolve.rs b/cli/src/services/repository_identity/resolve.rs index 6c2db6f1d..abc48b871 100644 --- a/cli/src/services/repository_identity/resolve.rs +++ b/cli/src/services/repository_identity/resolve.rs @@ -1,15 +1,3 @@ -//! Runtime repository identity resolution. -//! -//! Applies the repository identity precedence: an explicit configured -//! identity (`agent_trace.repository_id`) wins, otherwise the URL of the -//! configured Git remote (`agent_trace.repository_remote`, default `origin`) -//! is canonicalized, otherwise resolution fails with actionable -//! `.sce/config.json` guidance. Local paths are never used implicitly. -//! -//! Errors intentionally never echo remote URLs so credential-bearing -//! remotes cannot leak through diagnostics; remote names are operator-chosen -//! configuration values and are safe to display. - use std::path::Path; use std::process::Command; @@ -20,37 +8,28 @@ use super::{ RepositoryIdentityError, }; -/// Where a resolved repository identity came from. #[derive(Debug, Clone, PartialEq, Eq)] pub enum RepositoryIdentitySource { - /// Explicit `agent_trace.repository_id` configuration value. ExplicitConfig, - /// URL of the named Git remote. RemoteUrl { remote_name: String }, } -/// A repository identity plus the source it was resolved from. #[derive(Debug, Clone, PartialEq, Eq)] pub struct ResolvedRepositoryIdentity { pub identity: RepositoryIdentity, pub source: RepositoryIdentitySource, } -/// Resolution failure. Variants never carry remote URLs or explicit -/// identity values, only the configured remote name. #[derive(Debug, Clone, PartialEq, Eq)] pub enum RepositoryIdentityResolutionError { - /// `agent_trace.repository_id` is configured but unusable. InvalidExplicitIdentity(RepositoryIdentityError), - /// The configured remote exists but its URL cannot serve as a - /// repository identity (for example a local path remote). InvalidRemoteUrl { remote_name: String, error: RepositoryIdentityError, }, - /// No explicit identity is configured and the configured remote has - /// no URL. - MissingIdentity { remote_name: String }, + MissingIdentity { + remote_name: String, + }, } impl std::fmt::Display for RepositoryIdentityResolutionError { @@ -74,8 +53,6 @@ impl std::fmt::Display for RepositoryIdentityResolutionError { impl std::error::Error for RepositoryIdentityResolutionError {} -/// Resolves the repository identity for a Git repository checkout, applying -/// the explicit-config-then-remote precedence. pub fn resolve_repository_identity( repository_root: &Path, explicit_identity: Option<&str>, @@ -86,8 +63,6 @@ pub fn resolve_repository_identity( }) } -/// Precedence core with an injectable remote URL lookup, so callers and -/// tests can resolve without spawning `git`. pub fn resolve_repository_identity_with_lookup( explicit_identity: Option<&str>, remote_name: &str, @@ -122,17 +97,12 @@ pub fn resolve_repository_identity_with_lookup( }) } -/// Reads the URL of a named Git remote from repository configuration. -/// Returns `None` when git is unavailable, the directory is not a -/// repository, or the remote has no URL. pub fn lookup_remote_url(repository_root: &Path, remote_name: &str) -> Option { lookup_remote_url_strict(repository_root, remote_name) .ok() .flatten() } -/// Reads a named Git remote URL while distinguishing a missing URL from a -/// failure to execute or interpret the lookup. pub fn lookup_remote_url_strict( repository_root: &Path, remote_name: &str, diff --git a/cli/src/services/resilience.rs b/cli/src/services/resilience.rs index 3fca25337..ba0899cea 100644 --- a/cli/src/services/resilience.rs +++ b/cli/src/services/resilience.rs @@ -158,10 +158,6 @@ where )) } -/// One retryable attempt. Closures returning a future implement it directly; -/// operations that must lend an exclusive borrow (such as a transaction on a -/// single connection) implement it on a struct, because an `FnMut` closure -/// cannot return a future that borrows its own captured `&mut` state. pub trait RetryOperation { async fn run(&mut self, attempt: u32) -> Result; } diff --git a/cli/src/services/security.rs b/cli/src/services/security.rs index f4945c6bc..93aaaf005 100644 --- a/cli/src/services/security.rs +++ b/cli/src/services/security.rs @@ -171,7 +171,6 @@ pub fn ensure_directory_is_writable(path: &std::path::Path, context: &str) -> Re ) })?; - // Clean up probe file; best-effort with warning on failure if let Err(e) = std::fs::remove_file(&probe_path) { eprintln!( "Warning: Failed to clean up write-probe file '{}': {}", diff --git a/cli/src/services/structured_patch.rs b/cli/src/services/structured_patch.rs index 1fdcc6d5b..824eb74cd 100644 --- a/cli/src/services/structured_patch.rs +++ b/cli/src/services/structured_patch.rs @@ -1,11 +1,3 @@ -//! Structured editor-hook patch derivation. -//! -//! This module converts supported structured tool payloads into the CLI's -//! canonical [`ParsedPatch`](crate::services::patch::ParsedPatch) domain model -//! without going through rendered unified-diff text. The first supported source -//! is Claude `PostToolUse` payloads for `Write` creates and `Edit` structured -//! patches. - use std::fmt; use std::path::{Path, PathBuf}; @@ -22,8 +14,6 @@ pub struct ClaudeStructuredPatch { pub time: u64, pub tool_name: String, pub tool_version: Option, - /// The payload's absolute `cwd`, the base of any relative patch path. - /// `None` when `cwd` is missing, empty, or not absolute. pub working_directory: Option, } @@ -439,8 +429,6 @@ fn normalize_optional_version(value: Option<&Value>) -> VersionField { } } -/// The payload `cwd` only when it is absolute: a relative `cwd` cannot anchor -/// a relative patch path. fn absolute_cwd(payload: &Map) -> Option { string_field(payload, &["cwd"]).filter(|cwd| Path::new(cwd).is_absolute()) } diff --git a/cli/src/services/style.rs b/cli/src/services/style.rs index 903c884eb..7645d0efe 100644 --- a/cli/src/services/style.rs +++ b/cli/src/services/style.rs @@ -77,11 +77,6 @@ pub(crate) fn error_code_with_color_policy(text: &str, color_enabled: bool) -> S style_if(text, color_enabled, |s| s.red().bold().to_string()) } -/// Styles human-readable stderr diagnostic bodies (yellow), following the -/// stderr TTY/`NO_COLOR` policy passed in by the caller. `app_support`'s -/// error-diagnostic renderer is the sole caller in production, threading -/// `supports_color_stderr()` through explicitly so the same code path is -/// exercisable with an injected policy in tests. #[must_use] pub(crate) fn error_text_with_color_policy(text: &str, color_enabled: bool) -> String { style_if(text, color_enabled, |s| s.yellow().to_string()) @@ -269,24 +264,14 @@ pub(crate) fn banner_link_with_color_policy(text: &str, url: &str, color_enabled }) } -/// Gradient color endpoints for the ASCII art banner. -/// Right side: cyan (0, 255, 255), Left side: magenta (255, 0, 255). const GRADIENT_COLOR_RIGHT: (u8, u8, u8) = (0, 255, 255); const GRADIENT_COLOR_LEFT: (u8, u8, u8) = (255, 0, 255); -/// Applies a right-to-left color gradient to ASCII art banner lines. -/// -/// When color is enabled, each non-space character is colored based on its -/// column position using a cyan-to-magenta gradient (cyan on the right, -/// magenta on the left). Spaces are left unstyled. -/// When color is disabled, returns the plain ASCII art unchanged. #[must_use] pub fn banner_with_gradient(lines: &[&str]) -> String { banner_with_gradient_with_color_policy(lines, supports_color()) } -/// Internal variant of [`banner_with_gradient`] that accepts an explicit -/// color policy flag for testability. #[allow(clippy::cast_precision_loss)] #[must_use] pub(crate) fn banner_with_gradient_with_color_policy( @@ -330,10 +315,6 @@ pub(crate) fn banner_with_gradient_with_color_policy( .join("\n") } -/// Linear interpolation between two `u8` values. -/// -/// Returns `a + (b - a) * t`, clamped to the `u8` range by construction -/// since `a`, `b` are `u8` and `t` is in `[0, 1]`. #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)] fn lerp_u8(a: u8, b: u8, t: f64) -> u8 { (f64::from(a) + (f64::from(b) - f64::from(a)) * t).round() as u8 @@ -343,13 +324,6 @@ fn lerp_u8(a: u8, b: u8, t: f64) -> u8 { mod tests { use super::*; - // `supports_color_stderr()` combines the real stderr TTY check with the - // `NO_COLOR` check into one `color_enabled` boolean; a real TTY can't be - // simulated in `cargo test`, so these `_with_color_policy` seams (the same - // pattern used elsewhere in this module and in `doctor/render.rs`) are - // exercised directly against that boolean instead of mutating process - // environment state. - #[test] fn error_text_styles_when_color_enabled() { let styled = error_text_with_color_policy("boom", true); @@ -359,8 +333,6 @@ mod tests { #[test] fn error_text_is_plain_when_color_disabled() { - // Covers both a non-TTY stderr (redirected) and `NO_COLOR` being set, - // since both collapse to `color_enabled: false`. assert_eq!(error_text_with_color_policy("boom", false), "boom"); } diff --git a/cli/src/services/sync/auto_sync.rs b/cli/src/services/sync/auto_sync.rs index 6b27d4e10..069f88f57 100644 --- a/cli/src/services/sync/auto_sync.rs +++ b/cli/src/services/sync/auto_sync.rs @@ -1,5 +1,3 @@ -//! Best-effort launcher for one-shot automatic Agent Trace synchronization. - use std::io; use std::path::{Path, PathBuf}; use std::process::{Command, Stdio}; @@ -34,8 +32,6 @@ impl AutoSyncCommand { } } -/// Launches the current executable to synchronize the repository in the -/// background. Launcher failures are intentionally ignored by the caller. pub fn launch(repository_root: &Path) { let _ = launch_with(repository_root, std::env::current_exe, spawn_command); } @@ -65,8 +61,6 @@ fn spawn_command(spec: AutoSyncCommand) -> io::Result<()> { .stdout(Stdio::null()) .stderr(Stdio::null()); - // Dropping Child does not wait for it; the spawned sync continues - // independently of the post-commit caller. let _child = command.spawn()?; Ok(()) } diff --git a/cli/src/services/sync/mod.rs b/cli/src/services/sync/mod.rs index 62046d2a4..121732e87 100644 --- a/cli/src/services/sync/mod.rs +++ b/cli/src/services/sync/mod.rs @@ -1,5 +1,3 @@ -//! Top-level `sce sync` command and Agent Trace synchronization service. - pub mod auto_sync; pub mod command; pub mod progress; diff --git a/cli/src/services/sync/progress.rs b/cli/src/services/sync/progress.rs index 4ca957b40..89806ae8f 100644 --- a/cli/src/services/sync/progress.rs +++ b/cli/src/services/sync/progress.rs @@ -1,5 +1,3 @@ -//! Sync-owned progress reporting contracts and terminal presentation. - use std::io::{self, IsTerminal, Write}; use std::time::Duration; @@ -7,14 +5,9 @@ use indicatif::{MultiProgress, ProgressBar, ProgressDrawTarget, ProgressStyle}; use super::sync::SyncProgressEvent; -/// Receives deterministic progress events and can finalize a successful run. pub trait ProgressReporter { fn report(&mut self, event: E); - /// Finalizes a successfully completed report. - /// - /// Reporters that do not need a separate successful-finalization step can - /// keep the default no-op implementation. fn finish_successfully(&mut self) {} } @@ -27,7 +20,6 @@ where } } -/// Discards progress for callers that only need the final result. #[derive(Clone, Copy, Debug, Default)] pub struct NoopProgressReporter; diff --git a/cli/src/services/sync/render_sync.rs b/cli/src/services/sync/render_sync.rs index 3063d2bfb..05ead21d1 100644 --- a/cli/src/services/sync/render_sync.rs +++ b/cli/src/services/sync/render_sync.rs @@ -1,5 +1,3 @@ -//! Renderers for `sce sync` (text and JSON). - use anyhow::{Context, Result}; use serde_json::json; diff --git a/cli/src/services/sync/sync.rs b/cli/src/services/sync/sync.rs index ecfaa8bee..fdfdbb58c 100644 --- a/cli/src/services/sync/sync.rs +++ b/cli/src/services/sync/sync.rs @@ -1,7 +1,3 @@ -//! Consumes the already-shipped [`crate::services::agent_trace_sync`] engine -//! and [`crate::services::agent_trace_sync::control_plane`] client as-is; adds -//! no local sync cursor or persisted progress of its own. - use std::cell::{Cell, RefCell}; use std::fmt; use std::future::{poll_fn, Future}; @@ -73,12 +69,10 @@ pub enum SyncProgressEvent { }, } -/// Supplies timestamps for one trace-sync invocation. pub trait SyncProgressClock { fn now(&self) -> DateTime; } -/// Uses the system UTC clock for production sync invocations. #[derive(Clone, Copy, Debug, Default)] pub struct SystemSyncProgressClock; @@ -95,15 +89,11 @@ where clock.now().to_rfc3339_opts(SecondsFormat::AutoSi, true) } -/// Terminal failure of `sce sync`. #[derive(Debug)] pub enum TraceSyncError { - /// Local repository/storage/config resolution failed. Runtime(String), AuthDisabled(AuthPolicyConfigFile), - /// The initial `/state` call failed terminally. ControlPlane(ControlPlaneError), - /// One stream failed to converge. Stream { stream: &'static str, source: StreamSyncError, @@ -124,11 +114,6 @@ impl fmt::Display for TraceSyncError { impl std::error::Error for TraceSyncError {} impl TraceSyncError { - /// True when this failure means the caller has no usable `WorkOS` - /// credentials, whether that surfaced from the initial `/state` call - /// (`ControlPlane`) or from a stream's batch/refresh path (`Stream`). - /// `Runtime` never carries a `ControlPlaneError` and is never an - /// authentication failure. pub fn is_authentication_failure(&self) -> bool { match self { Self::Runtime(_) | Self::AuthDisabled(_) => false, @@ -137,9 +122,6 @@ impl TraceSyncError { } } - /// True when the failure came from local credential storage, whether it - /// surfaced during the initial state request or a stream batch/refresh - /// path. pub fn storage_failure(&self) -> Option { match self { Self::ControlPlane(error) => error.storage_failure(), @@ -149,7 +131,6 @@ impl TraceSyncError { } } -/// Production sync entry point with injectable progress sink and clock. pub async fn run_current_sync_with_progress_and_clock( repo_root: &Path, progress: &mut S, @@ -505,12 +486,6 @@ where }) } -/// A control-plane failure that cannot be resolved by reconciling with -/// `/state`: missing/invalid credentials, an unrecoverable `401`, a `400`, a -/// `403` ownership rejection, or a terminal protocol/API mismatch -/// (`404`/`405`/`415`/`422`, `ControlPlaneError::Protocol`). `5xx`, transport -/// failures, and invalid batch responses are genuinely ambiguous and -/// reconcile via a real `/state` call. fn is_stream_terminal(error: &ControlPlaneError) -> bool { matches!( error, diff --git a/config/lib/agent-trace-plugin/opencode-sce-agent-trace-plugin.ts b/config/lib/agent-trace-plugin/opencode-sce-agent-trace-plugin.ts index c57c3e603..214a09c41 100644 --- a/config/lib/agent-trace-plugin/opencode-sce-agent-trace-plugin.ts +++ b/config/lib/agent-trace-plugin/opencode-sce-agent-trace-plugin.ts @@ -89,7 +89,6 @@ function extractDiffTracePayload( event: EventMessageUpdated, ): DiffTracePayload | undefined { const eventInfo = event.properties.info; - // Only capture user messages (filter out assistant, system, etc.) if (eventInfo.role !== "user") { return undefined; } @@ -334,9 +333,6 @@ async function runDiffTraceHook( await new Promise((resolve) => { const child = spawn("sce", ["hooks", "diff-trace"], { cwd: repoRoot, - // Fail-open: stderr is ignored so that sce intake errors - // (connection refused, timeout, etc.) do not leak into the - // OpenCode TUI. Resolve unconditionally on any outcome. stdio: ["pipe", "ignore", "ignore"], }); @@ -359,9 +355,6 @@ async function runConversationTraceHook( await new Promise((resolve) => { const child = spawn("sce", ["hooks", "conversation-trace"], { cwd: repoRoot, - // Fail-open: stderr is ignored so that sce intake errors - // (connection refused, timeout, etc.) do not leak into the - // OpenCode TUI. Resolve unconditionally on any outcome. stdio: ["pipe", "ignore", "ignore"], }); diff --git a/config/lib/bash-policy-plugin/bash-policy-runtime.test.ts b/config/lib/bash-policy-plugin/bash-policy-runtime.test.ts index 9e2edc969..5dda8098a 100644 --- a/config/lib/bash-policy-plugin/bash-policy-runtime.test.ts +++ b/config/lib/bash-policy-plugin/bash-policy-runtime.test.ts @@ -1,13 +1,11 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test"; -// Mock state for spawnSync calls let mockSpawnSyncResult: { status: number; stdout: string; error?: Error; } | null = null; -// Mock the node:child_process module to intercept spawnSync calls const { mock } = await import("bun:test"); mock.module("node:child_process", () => ({ spawnSync: ( @@ -52,7 +50,6 @@ mock.module("node:child_process", () => ({ }, })); -// Import the plugin after mocking const { SceBashPolicyPlugin } = await import( "./opencode-bash-policy-plugin.ts" ); @@ -97,7 +94,6 @@ describe("SceBashPolicyPlugin", () => { test("ignores non-bash tool events", async () => { const plugin = await SceBashPolicyPlugin({}); - // Should return undefined for non-bash tools const result = await plugin["tool.execute.before"]( { tool: "read" }, { args: { command: "git status" } }, @@ -153,7 +149,6 @@ describe("SceBashPolicyPlugin", () => { const plugin = await SceBashPolicyPlugin({}); - // Should return undefined (allow) without throwing const result = await plugin["tool.execute.before"]( { tool: "bash" }, { args: { command: "git status" } }, @@ -197,7 +192,6 @@ describe("SceBashPolicyPlugin", () => { const plugin = await SceBashPolicyPlugin({}); - // Should return undefined (allow) without throwing const result = await plugin["tool.execute.before"]( { tool: "bash" }, { args: { command: "git status" } }, @@ -251,8 +245,6 @@ describe("SceBashPolicyPlugin", () => { }); test("passes normalized input format to sce policy bash", () => { - // Verify that the normalized JSON request format matches - // what sce policy bash --input normalized expects const command = "git status"; const request = JSON.stringify({ command }); const parsed = JSON.parse(request); diff --git a/config/lib/bash-policy-plugin/opencode-bash-policy-plugin.ts b/config/lib/bash-policy-plugin/opencode-bash-policy-plugin.ts index 0b2b8d9c9..03cf59326 100644 --- a/config/lib/bash-policy-plugin/opencode-bash-policy-plugin.ts +++ b/config/lib/bash-policy-plugin/opencode-bash-policy-plugin.ts @@ -13,11 +13,6 @@ interface JsonPolicyResult { const SCE_INSTALL_URL = "https://sce.crocoder.dev/docs/getting-started#install-cli"; -/** - * Evaluate a bash command against SCE bash-tool policy by delegating to the - * Rust `sce policy bash` command. Returns the parsed JSON result, or null if - * the policy check could not be performed (fail-open). - */ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null { try { const result = spawnSync( @@ -72,7 +67,6 @@ export const SceBashPolicyPlugin: Plugin = async () => { const policyResult = evaluateBashCommandPolicy(command); if (!policyResult) { - // Fail open: if the policy check cannot be performed, allow the command. return; } diff --git a/config/lib/pi-plugin/sce-pi-extension.ts b/config/lib/pi-plugin/sce-pi-extension.ts index 54cb2576c..bd4311a62 100644 --- a/config/lib/pi-plugin/sce-pi-extension.ts +++ b/config/lib/pi-plugin/sce-pi-extension.ts @@ -94,11 +94,6 @@ type PendingFileMutation = { before: string | undefined; }; -/** - * Evaluate a bash command against SCE bash-tool policy by delegating to the - * Rust `sce policy bash` command. Returns the parsed JSON result, or null if - * the policy check could not be performed (fail-open). - */ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null { try { const result = spawnSync( @@ -134,11 +129,6 @@ function evaluateBashCommandPolicy(command: string): JsonPolicyResult | null { } } -/** - * Send a conversation-trace payload to `sce hooks conversation-trace`, - * fire-and-forget. Fail-open: stderr is ignored so that sce intake errors do - * not leak into the Pi TUI, and the returned promise never rejects. - */ function runConversationTraceHook( cwd: string, payload: ConversationTracePayload, @@ -228,12 +218,6 @@ function buildMessageEndConversationTracePayload( return { tool_name: TOOL_NAME, payloads }; } -/** - * Resolve the installed Pi package version for diff-trace `tool_version`. - * The package's `exports` map does not expose `package.json`, so resolve the - * package entry point and read `package.json` from the package root instead. - * Returns null when resolution fails (normalized diff traces permit it). - */ async function resolvePiToolVersion(): Promise { try { const entryPath = fileURLToPath( @@ -251,10 +235,6 @@ async function resolvePiToolVersion(): Promise { } } -/** - * Send a diff-trace payload to `sce hooks diff-trace`, fire-and-forget. - * Fail-open: stderr is ignored and the returned promise never rejects. - */ function runDiffTraceHook( cwd: string, payload: DiffTracePayload, @@ -292,11 +272,6 @@ function diffLabelFor(cwd: string, absolutePath: string): string { : absolutePath; } -/** - * Rewrite temp-file path labels in git diff header lines to the repo-relative - * target path. Only header lines before the first `@@` hunk marker are - * touched so that content lines starting with `--- ` / `+++ ` are preserved. - */ function rewriteDiffLabels( diff: string, label: string, @@ -319,12 +294,6 @@ function rewriteDiffLabels( return lines.join("\n"); } -/** - * Produce a unified diff between before/after contents by writing them to - * temp files and spawning `git diff --no-index --no-ext-diff` (exit status 1 - * means "files differ"). Returns undefined for no-op diffs or any failure; - * temp files are always cleaned up. - */ async function buildUnifiedDiff( label: string, before: string | undefined, @@ -775,7 +744,6 @@ export default function sceExtension(pi: ExtensionAPI): void { const policyResult = evaluateBashCommandPolicy(command); if (!policyResult) { - // Fail open: if the policy check cannot be performed, allow the command. return undefined; } diff --git a/config/lib/sce-info/tests/sce-splash.test.ts b/config/lib/sce-info/tests/sce-splash.test.ts index 7f8451518..e8bcf10b4 100644 --- a/config/lib/sce-info/tests/sce-splash.test.ts +++ b/config/lib/sce-info/tests/sce-splash.test.ts @@ -16,7 +16,6 @@ const BAND = { }, } as const -// Stands in for what Claude Code (or a mod after this one) draws in the band function drawBeneath(on: On) { on('ui.render', { component: 'AbovePrompt' }, ($, e) => { const { Text } = $.ui.resolve(e) @@ -33,7 +32,6 @@ test('the startup band shows the "SCE" art once and keeps what is beneath it', a expect(await ui.findAll({ type: 'Link', text: SITE })).toHaveLength(1) expect(await ui.find({ type: 'Text', text: 'beneath' })).toBeDefined() - // Redraws don't stack a second label await ui.redraw() await ui.redraw() for (const row of ART) expect(await ui.findAll({ type: 'Text', text: row })).toHaveLength(1) @@ -48,7 +46,6 @@ test('the label yields to a survey', async ($, on) => { test('the label leaves once the first prompt is sent', async ($, on) => { drawBeneath(on) - // Answer in Claude Code's place, so the prompt goes nowhere on('prompt.submit', ($, e) => ({ text: e.text })) const ui = await $.ui.mount(BAND) expect(await ui.find({ type: 'Text', text: ART[0] })).toBeDefined() @@ -61,7 +58,6 @@ test('the label leaves once the first prompt is sent', async ($, on) => { test('the label comes back after a /clear', async ($, on) => { drawBeneath(on) on('prompt.submit', ($, e) => ({ text: e.text })) - // Claude Code's own end step on('session.end', ($, e) => ({ sessionId: e.sessionId })) const ui = await $.ui.mount(BAND) await $.prompt.submit({ text: 'hello', wait: false, origin: { kind: 'composer' } }) @@ -70,7 +66,6 @@ test('the label comes back after a /clear', async ($, on) => { await $.session.end({ reason: 'clear', sessionId: 's1', resume: { id: 's1' } }) expect(await ui.findAll({ type: 'Text', text: ART[0] })).toHaveLength(1) - // And leaves again on the next prompt await $.prompt.submit({ text: 'again', wait: false, origin: { kind: 'composer' } }) expect(await ui.find({ type: 'Text', text: ART[0] })).toBeUndefined() }) diff --git a/config/pkl/base/decision-skill.pkl b/config/pkl/base/decision-skill.pkl index f0c2ca9ab..c8893cb7d 100644 --- a/config/pkl/base/decision-skill.pkl +++ b/config/pkl/base/decision-skill.pkl @@ -1,9 +1,5 @@ import "workflow-content.pkl" as model -/// Canonical standalone decision-writing package. It is intentionally outside -/// the workflow catalog because synchronization invokes it internally; no -/// user-facing command or prompt routes to this skill. - local SKILL_SLUG = "sce-decision" local SKILL_DESCRIPTION = "Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present" diff --git a/config/pkl/base/optional-workflow-manifest.pkl b/config/pkl/base/optional-workflow-manifest.pkl index 111b3faf9..df175532c 100644 --- a/config/pkl/base/optional-workflow-manifest.pkl +++ b/config/pkl/base/optional-workflow-manifest.pkl @@ -1,8 +1,3 @@ -// Install-time view of the workflow catalog: the workflows a repository must -// select explicitly before their generated assets are installed. Generation -// content is unaffected — every catalog workflow is still generated for every -// target — so this manifest exists only to carry optional workflow identity -// out of Pkl and into the CLI. import "workflow-catalog.pkl" as catalog class OptionalWorkflowRecord { diff --git a/config/pkl/base/workflow-brownfield.pkl b/config/pkl/base/workflow-brownfield.pkl index c6b29cde4..15815b950 100644 --- a/config/pkl/base/workflow-brownfield.pkl +++ b/config/pkl/base/workflow-brownfield.pkl @@ -1,18 +1,5 @@ import "workflow-content.pkl" as model -/// Canonical `/brownfield` workflow command and its self-contained -/// `sce-brownfield` skill package. Text mirrors the project-root `.pi/` -/// behavioral baseline; target renderers consume this model in later -/// workflow-rendering tasks. -/// -/// Like `sce-handover`, `sce-brownfield` invokes no sibling phase, so its -/// `phases` listing is empty and composite rendering emits no phase appendix. -/// Unlike `sce-handover` it does wait mid-run, at the blocking clarification -/// gate, which the composite preamble's own control-flow paragraph already -/// covers. The one preamble statement that paragraph does not carry is the -/// cold-start and gap-fill scope, so that paragraph is the composite spelling of -/// the package preamble rather than being dropped. - local COMMAND = """ --- description: "Reconstruct durable context from an existing repository's own evidence" @@ -380,9 +367,6 @@ local structuredCommand = new model.StructuredWorkflowDocument { local SKILL = structuredCommand.render.apply("package", "").text -/// Custom string delimiters: the fact-ledger table row escapes its column -/// separators as `\|`, which a default Pkl string would reject as an unknown -/// escape sequence. local OUTPUT_MD = (argumentsReference: String) -> #""" # Brownfield output layouts diff --git a/config/pkl/base/workflow-catalog.pkl b/config/pkl/base/workflow-catalog.pkl index 47852c871..c5ded3922 100644 --- a/config/pkl/base/workflow-catalog.pkl +++ b/config/pkl/base/workflow-catalog.pkl @@ -1,6 +1,3 @@ -/// Target-neutral workflow identity plus the small amount of target routing -/// metadata that varies by workflow. Content modules and renderers remain -/// responsible for workflow behavior and output formatting. class WorkflowRecord { commandSlug: String skillSlug: String @@ -10,9 +7,6 @@ class WorkflowRecord { openCodeAgentSlug: String claudeAllowedTools: String - /// An optional workflow is generated for every target like any other, but is - /// installed only when a repository explicitly selects it. Core workflows - /// leave this at `false`. optional: Boolean = false } diff --git a/config/pkl/base/workflow-change-to-plan.pkl b/config/pkl/base/workflow-change-to-plan.pkl index 80483fa22..c17fd0861 100644 --- a/config/pkl/base/workflow-change-to-plan.pkl +++ b/config/pkl/base/workflow-change-to-plan.pkl @@ -841,10 +841,6 @@ local contextLoadHeadings = new model.PhaseHeadings { step = 1 } local planAuthoringHeadings = new model.PhaseHeadings { step = 2 } local planTemplateHeadings = new model.PhaseHeadings { step = 0 } -/// Contract references. A package owns `references/*.yaml`, so these sentences -/// resolve there. A composite workflow has no such file and describes its -/// internal states inline, so the reference would resolve to nothing and is -/// dropped. Each block-shaped reference owns its surrounding blank lines. local contextBriefHandoffSentence = model.semanticReference.apply( """ @@ -886,10 +882,6 @@ local authoringContractClause = model.semanticReference.apply(" matching `refere local returnExactlyOneStructuredResult = model.semanticReference.apply("Return exactly one structured result", "Set exactly one internal state") local returnOnlyStructuredResult = model.semanticReference.apply("Return only the structured result", "Record only the internal state") -/// User-visible layouts. Package mode states each layout at its branch, because a -/// command file has no sibling `references/output.md`. Composite mode cites the -/// `output.md` section that owns the layout, and keeps only the field mapping, -/// branch conditions, and prohibitions that travelled with it. local bootstrapLayout = model.semanticReference.apply( """ Return: @@ -973,10 +965,6 @@ local readyContinuationLayout = model.semanticReference.apply( """ ) -/// Canonical `/change-to-plan` workflow command and its self-contained skill -/// packages. Text mirrors the project-root `.pi/` behavioral baseline; target -/// renderers consume this model in later workflow-rendering tasks. - local contextLoadPackage = new model.SkillPackage { slug = "sce-context-load" title = "SCE Context Load" diff --git a/config/pkl/base/workflow-commit.pkl b/config/pkl/base/workflow-commit.pkl index 27c098049..9117d35e2 100644 --- a/config/pkl/base/workflow-commit.pkl +++ b/config/pkl/base/workflow-commit.pkl @@ -4,10 +4,6 @@ local atomicCommit = model.semanticReference.apply("`sce-atomic-commit`", "the * local atomicCommitUpper = model.semanticReference.apply("`sce-atomic-commit`", "The **Atomic commit phase**") local atomicCommitName = model.semanticReference.apply("sce-atomic-commit", "Atomic commit phase") local atomicCommitHeadings = new model.PhaseHeadings { step = 2; compositeShift = 2 } -/// The bypass path invokes the same phase inlined at the regular path's -/// proposing step. Composite mode points back to it instead of restating it; -/// package mode has no such forward concern, since the phase is its own -/// document there. local bypassPhaseReferenceQualifier = model.semanticReference.apply( "", " (described at the Regular path's step 2 above)" @@ -29,10 +25,6 @@ local commitContractHandoff = model.semanticReference.apply( "Branch on `status`:" ) -/// User-visible layouts. Package mode states each layout at its branch, because a -/// command file has no sibling `references/output.md`. Composite mode cites the -/// `output.md` section that owns the layout, and keeps only the field mapping, -/// branch conditions, and prohibitions that travelled with it. local noStagedChangesLayout = model.semanticReference.apply( """ When nothing is staged, stop with exactly: @@ -92,10 +84,6 @@ local proposalBranch = model.semanticReference.apply( """ ) -/// Canonical `/commit` workflow command and its self-contained skill package. -/// Text mirrors the project-root `.pi/` behavioral baseline; target renderers -/// consume this model in later workflow-rendering tasks. - local atomicCommitPackage = new model.SkillPackage { slug = "sce-atomic-commit" title = "SCE Atomic Commit" diff --git a/config/pkl/base/workflow-content.pkl b/config/pkl/base/workflow-content.pkl index 588948945..03263e72a 100644 --- a/config/pkl/base/workflow-content.pkl +++ b/config/pkl/base/workflow-content.pkl @@ -1,9 +1,3 @@ -/// Canonical model for workflow-oriented Markdown generation. -/// -/// A workflow owns commands and self-contained skill packages. Package document -/// paths are relative to the skill root, so nested references can be rendered -/// deterministically for every target without cross-skill dependencies. - class WorkflowDocument { path: String text: String @@ -11,8 +5,6 @@ class WorkflowDocument { typealias WorkflowRenderMode = "package"|"composite" -/// A semantic token whose spelling depends on whether a canonical package or -/// an embedded composite workflow is being rendered. class SemanticReference { packageText: String compositeText: String @@ -21,50 +13,31 @@ class SemanticReference { if (mode == "composite") compositeText else packageText } -/// Markdown heading marker for a heading level. Heading depth is always -/// constructed from a level, never written as a literal run of `#` that a later -/// pass would have to rewrite. hidden const headingMarker = (level: Int) -> "#".repeat(level) -/// Heading construction for a phase body. A canonical package renders the phase -/// as its own document; composite rendering states the same body inside the -/// numbered workflow step that runs it, so every heading shifts one level deeper -/// and every phase step is renumbered `{step}.{n}`. class PhaseHeadings { - /// Workflow step whose instructions this phase body carries in composite mode. step: Int - /// Heading levels composite rendering adds to every heading below. hidden compositeShift: Int = 1 hidden shift = (mode: WorkflowRenderMode) -> if (mode == "composite") compositeShift else 0 - /// A top-level section of the phase body: `## Boundaries` as a package - /// document, `### Boundaries` inlined beneath its step. hidden section = (mode: WorkflowRenderMode, text: String) -> headingMarker.apply(2 + shift.apply(mode)) + " " + text - /// A numbered step of the phase body: `### 3. Inspect relevant context` as a - /// package document, `#### 1.3 Inspect relevant context` inlined beneath - /// workflow step 1. hidden stepHeading = (mode: WorkflowRenderMode, index: Int, text: String) -> if (mode == "composite") headingMarker.apply(3 + compositeShift) + " \(step).\(index) \(text)" else headingMarker.apply(3) + " \(index). \(text)" - /// A heading nested inside a numbered phase step, such as `#### Glossary`. hidden stepSubsection = (mode: WorkflowRenderMode, text: String) -> headingMarker.apply(4 + shift.apply(mode)) + " " + text - /// A cross-reference to one of the phase's own steps: `step 3` as a package - /// document, `step 1.3` inlined beneath workflow step 1. hidden stepReference = (mode: WorkflowRenderMode, index: Int) -> if (mode == "composite") "step \(step).\(index)" else "step \(index)" } -/// Frontmatter is modeled separately so composite rendering can drop it without -/// parsing or stripping Markdown markers. class WorkflowFrontmatter { hidden lines: (WorkflowRenderMode) -> Listing @@ -72,7 +45,6 @@ class WorkflowFrontmatter { "---\n" + lines.apply(mode).join("\n") + "\n" + extraLines + "---\n" } -/// A body renderer receives semantic render mode before Markdown assembly. class WorkflowBody { hidden render: (WorkflowRenderMode) -> String } @@ -94,36 +66,14 @@ class StructuredWorkflowDocument { class StructuredCompositeSource { command: StructuredWorkflowDocument - /// Complete workflow body for a phase-reference package. When present, the - /// composite renderer uses this body instead of inlining phase instructions. - /// Parameterized by the target's arguments-reference token so skill-mode - /// prose can name the invocation input without a literal `$ARGUMENTS` for a - /// target whose harness does not substitute it, and by a target-specific - /// concrete `$sce-{slug}` invocation example appended to `## Input` (empty - /// for targets that need none). compositeSkillBody: ((String, String) -> String)? = null - /// The composite command body's own `## Input`/`## Workflow` text, for a - /// phase-free workflow (no `compositeSkillBody`) whose command body names the - /// invocation input directly, parameterized the same way. When present, the - /// generic composite renderer uses this instead of `command`'s mode-only - /// render, keeping that renderer's own shared preamble/appendix wrapper. argumentDependentCommandBody: ((String, String) -> String)? = null - /// Package-local documents read only when their owning workflow step runs. - /// Phase-based workflows include output.md here; phase-free workflows keep - /// using outputDocuments for their sole reference. referenceDocuments: Listing = new Listing {} - /// The workflow's own `references/output.md`, for a workflow whose output - /// layouts quote the received invocation input back to the user. Present - /// only where that quoting occurs; other workflows' output.md carries no - /// argument-dependent content and stays a plain `referenceDocuments` entry. argumentReferenceOutputDocument: ((String) -> WorkflowDocument)? = null - /// Phase documents still rendered as a trailing appendix. A module that - /// states every phase inside the step that runs it lists none, and composite - /// rendering then emits no appendix at all. phases: Listing = new Listing {} internalDocuments: Listing @@ -166,37 +116,18 @@ hidden semanticReference = (packageValue: String, compositeValue: String) -> new compositeText = compositeValue } -/// A block only package rendering emits, carrying the blank line that separates -/// it from what follows. Composite rendering emits nothing, so no call site is -/// left with a stray separator to strip. hidden packageOnlyBlock = (blockText: String) -> semanticReference.apply(blockText + "\n\n", "") -/// A block only composite rendering emits, under the same separator convention -/// as `packageOnlyBlock`. hidden compositeOnlyBlock = (blockText: String) -> semanticReference.apply("", blockText + "\n\n") -/// The `SCE $ARGUMENTS` banner a canonical command document opens -/// with. A composite skill states its input contract under its own `## Input` -/// heading directly below the skill title, so the banner belongs to package -/// rendering alone. hidden commandBanner = (workflowName: String) -> packageOnlyBlock.apply("\(workflowName) `$ARGUMENTS`") -/// A phase body placed at the workflow step that runs it. A canonical package -/// renders the phase as its own document, so the step only names it; composite -/// rendering states the phase's whole body inside the step. hidden inlinePhaseBody = (phaseBody: WorkflowBody) -> compositeOnlyBlock.apply(phaseBody.render.apply("composite")) -/// A concrete `$sce-{slug}` invocation example appended to a skill's `## Input` -/// section. Only Codex needs this: its skill loading has no `$ARGUMENTS`-style -/// substitution, so its Input section otherwise names the invocation input only -/// in prose. Empty for every other target, so their rendered Markdown is -/// byte-identical to before this paragraph existed. hidden invocationExampleParagraph = (invocationExample: String) -> if (invocationExample.isEmpty) "" else "For example: `\(invocationExample)`.\n\n" -/// Non-SCE skills may help with work inside the active workflow step without -/// becoming an alternate owner of the workflow's control flow. helperSkillCompositionRule = """ Relevant non-SCE skills may be used as helper capabilities during the active step. They are not workflow handoffs: when a helper returns, control returns to the active @@ -204,11 +135,6 @@ step. Helper use must preserve the canonical phase order, gates, waits, writes, validation, stops, and terminal user-visible output. """ -/// Canonical composite workflow bodies and package-local references for the -/// four phase-based workflows. Target renderers add only supported entrypoint -/// frontmatter; all operational and persisted-document content remains -/// target-neutral. -/// Compact emitted contract. Legacy helper prose stays unchanged for other consumers. typealias ExecutionContractVariant = "standard"|"task-decision" hidden executionContract = (variant: ExecutionContractVariant) -> diff --git a/config/pkl/base/workflow-context-sync.pkl b/config/pkl/base/workflow-context-sync.pkl index 415636c20..980d16954 100644 --- a/config/pkl/base/workflow-context-sync.pkl +++ b/config/pkl/base/workflow-context-sync.pkl @@ -22,9 +22,6 @@ local decisionSkill = "`sce-decision`" local packageOnlyBlock = workflow.packageOnlyBlock local compositeOnlyBlock = workflow.compositeOnlyBlock -/// One canonical source for both context-sync packages. Named SKILL and report -/// sections preserve semantic ordering while role data owns lifecycle-specific -/// content. class SyncReportRole { title: String inputStatus: (workflow.WorkflowRenderMode) -> String @@ -1490,7 +1487,6 @@ local documentMapping = (documents: Listing) -> new M } } -/// Shared materialization skeleton parameterized by lifecycle role. local packageFor = (role: SyncRole) -> new workflow.SkillPackage { slug = role.slug title = role.title diff --git a/config/pkl/base/workflow-handover.pkl b/config/pkl/base/workflow-handover.pkl index fc874554e..c9fd51e2a 100644 --- a/config/pkl/base/workflow-handover.pkl +++ b/config/pkl/base/workflow-handover.pkl @@ -1,14 +1,5 @@ import "workflow-content.pkl" as model -/// Canonical `/handover` workflow command and its self-contained `sce-handover` -/// skill package. Text mirrors the project-root `.pi/` behavioral baseline; -/// target renderers consume this model in later workflow-rendering tasks. -/// -/// Unlike the other canonical workflows, `sce-handover` invokes no sibling -/// phase and waits for nothing mid-run, so package and composite rendering -/// differ only by frontmatter, title, and the generic preamble sections a -/// composite skill receives from its renderer. - local COMMAND = """ --- description: "Write a session handover document, or load one for continuation" diff --git a/config/pkl/base/workflow-next-task.pkl b/config/pkl/base/workflow-next-task.pkl index 8f6725314..7e6b68220 100644 --- a/config/pkl/base/workflow-next-task.pkl +++ b/config/pkl/base/workflow-next-task.pkl @@ -27,10 +27,6 @@ local invokeTaskExecution = model.semanticReference.apply("Invoke task execution local planReviewHeadings = new model.PhaseHeadings { step = 1 } local taskExecutionHeadings = new model.PhaseHeadings { step = 2 } -/// Contract references. A package owns `references/*-contract.yaml`, so these -/// sentences resolve there. A composite workflow has no such file and describes -/// its internal states inline, so the reference would resolve to nothing and is -/// dropped. Each block-shaped reference owns its surrounding blank lines. local readinessHandoffSentence = model.semanticReference.apply( """ @@ -83,10 +79,6 @@ local executionCompletionBullet = model.semanticReference.apply( "- One valid terminal internal state was returned." ) -/// User-visible layouts. Package mode states each layout at its branch, because a -/// command file has no sibling `references/output.md`. Composite mode cites the -/// `output.md` section that owns the layout, and keeps only the field mapping, -/// branch conditions, and prohibitions that travelled with it. local reviewBlockedBranch = model.semanticReference.apply( """ `blocked` -> Do not invoke implementation. Present the result as prose. Do not print the raw result. Stop. @@ -219,10 +211,6 @@ local continuationLayouts = model.semanticReference.apply( """ ) -/// Canonical `/next-task` workflow command and its self-contained skill -/// packages. Text mirrors the project-root `.pi/` behavioral baseline; target -/// renderers consume this model in later workflow-rendering tasks. - local planReviewPackage = new model.SkillPackage { slug = "sce-plan-review" title = "SCE Plan Review" diff --git a/config/pkl/base/workflow-validate.pkl b/config/pkl/base/workflow-validate.pkl index cfd4617ea..77b34b9af 100644 --- a/config/pkl/base/workflow-validate.pkl +++ b/config/pkl/base/workflow-validate.pkl @@ -3,18 +3,12 @@ import "workflow-content.pkl" as model local validation = model.semanticReference.apply("`sce-validation`", "the **Validation phase**") local validationUpper = model.semanticReference.apply("`sce-validation`", "The **Validation phase**") local validationName = model.semanticReference.apply("sce-validation", "Validation phase") -/// Cited from inside `references/validation.md` itself, where the Validation -/// Result contract is now appended below the phase steps. local validationResultSelfRef = model.semanticReference.apply( "the **Validation report** section below in this file", "the **Validation report** section below in this file" ) -/// Cited from `references/validation-report.md`, a sibling file, so it must -/// name `references/validation.md` explicitly rather than say "below". local validationResultFileRef = model.semanticReference.apply("`references/validation.md`", "`references/validation.md`") local validationReport = model.semanticReference.apply("`references/validation-report.md`", "the **Plan-file validation report** section embedded in this file") -/// The paragraph that separates the plan-file report from the returned result. -/// Both spellings wrap at the same width as the surrounding body text. local reportVersusResult = model.semanticReference.apply( """ The plan-file `## Validation Report` section is written separately using @@ -27,9 +21,6 @@ local reportVersusResult = model.semanticReference.apply( carries the validation phase's result into the workflow's own branches. """ ) -/// The validation handoff sentence. A package owns -/// `references/output.md`, so naming that contract resolves there. A composite -/// workflow uses the same emitted document, so the reference remains unchanged. local validationResultHandoff = model.semanticReference.apply( """ The phase must return a Markdown report matching its validation report contract. @@ -51,9 +42,6 @@ local yaml = model.semanticReference.apply("YAML", "internal state") local validationHeadings = new model.PhaseHeadings { step = 1 } local validationReportHeadings = new model.PhaseHeadings { step = 0 } -/// User-visible layouts. Package mode states each layout at its branch, because a -/// command file has no sibling `references/output.md`. Composite mode cites the -/// `output.md` section that owns the layout. local completionLayout = model.semanticReference.apply( """ ``` @@ -73,10 +61,6 @@ local completionLayout = model.semanticReference.apply( """ ) -/// Canonical `/validate` workflow command and its self-contained skill -/// packages. Text mirrors the project-root `.pi/` behavioral baseline; target -/// renderers consume this model in later workflow-rendering tasks. - local validationPackage = new model.SkillPackage { slug = "sce-validation" title = "SCE Validation" @@ -584,14 +568,8 @@ local renderValidationResult = (mode: model.WorkflowRenderMode) -> """ local VALIDATION_RESULT = renderValidationResult.apply("package") -/// `references/validation.md` carries both the phase steps and the result -/// contract, so the phase's own citation of the result contract must point -/// within this same file rather than at a separate `references/output.md`. local VALIDATION_REFERENCE = renderValidationSkillBody.apply("package") + "\n\n" + VALIDATION_RESULT -/// Composite-only user-visible layouts. The validation report contract lives -/// in the validation reference, while this file carries the completion layout -/// cited by the composite `SKILL.md`. local VALIDATE_OUTPUT_LAYOUTS = """ # Validate output layouts diff --git a/config/pkl/deps/org.json_schema/JsonSchema.pkl b/config/pkl/deps/org.json_schema/JsonSchema.pkl index a8bea04a5..e061b1788 100644 --- a/config/pkl/deps/org.json_schema/JsonSchema.pkl +++ b/config/pkl/deps/org.json_schema/JsonSchema.pkl @@ -1,24 +1,3 @@ -//===----------------------------------------------------------------------===// -// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved. -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -//===----------------------------------------------------------------------===// -/// A document that describes constraints on JSON values. -/// -/// Currently only supports JSON Schema 6 or higher. -/// JSON Schema 4 isn't supported because of breaking changes in how [exclusiveMinimum] and [exclusiveMaximum] work. -/// -/// JSON Schema documentation can be found at . open module org.json_schema.JsonSchema import "pkl:reflect" @@ -38,24 +17,15 @@ typealias JsonSchemaVersion = typealias JsonSchemaValue = Boolean|Number|Null|String|Dynamic|Typed|Listing|Mapping -/// A JSON Schema can either be a [JsonSchema] object or a simple boolean. -/// -/// A boolean schema is shorthand for: -/// - true: Any value is valid -/// - false: No value is valid typealias Schema = *JsonSchema|Boolean -/// The known versions of JSON Schema. -/// -/// For example, `http://json-schema.org/draft-06/schema#`. hidden versions: List = (reflect.TypeAlias(JsonSchemaVersion).referent as reflect.UnionType).members .filterIsInstance(reflect.StringLiteralType) .map((it) -> it.value) -/// Ensures that this document's [`$schema`] is later than [version]. local function availableAfter(version: JsonSchemaVersion) = - if ($schema == null) // If $schema is unset, skip this check. + if ($schema == null) true else let (currentVersion = versions.indexOfOrNull($schema)) @@ -67,231 +37,60 @@ local function availableAfter(version: JsonSchemaVersion) = local parseUri = (it) -> URI.parse(it) -/// The base-level schema. -/// -/// This is a utility property to help with resolving references. hidden $$baseSchema: JsonSchema? -/// The ID as an instance of [URI]. -hidden /** final */ $$idUri: URI? = $id?.ifNonNull(parseUri) - -/// The reference as an instance of [URI]. -hidden /** final */ $$refUri: URI? = $ref?.ifNonNull(parseUri) - -// region Core -/// URI-reference for the schema. -/// -/// The reference serves two purposes: -/// -/// * It declares a unique identifier for the schema. -/// * It declares a base URI against which `$ref` URI-references are resolved. -/// -/// It is best practice that every top-level schema should set `$id` to an -/// absolute-URI (not a relative reference), with a domain that you control. -/// -/// +hidden $$idUri: URI? = $id?.ifNonNull(parseUri) + +hidden $$refUri: URI? = $ref?.ifNonNull(parseUri) + $id: String? -/// Reference to a schema. -/// -/// $ref: String? -/// The presence of this property declares that this object represents a JSON Schema, and also -/// represents the version that the schema was written against. -/// -/// It is recommended that all JSON Schemas have a [`$schema`] entry, -/// which must be at the root. Therefore most of the time, you'll want -/// this at the root of your schema: -/// -/// "$schema": "http://json-schema.org/draft/2019-09/schema#" -/// -/// $schema: JsonSchemaVersion? -/// Implementation comments for a schema. -/// -/// Its value must always be a string. Unlike the annotations -/// [title], [description], and [examples], JSON schema -/// implementations aren't allowed to attach any meaning or behavior to it -/// whatsoever, and may even strip them at any time. Therefore, they are -/// useful for leaving notes to future editors of a JSON schema, but -/// should not be used to communicate to users of the schema. -/// -/// $comment: String(availableAfter("http://json-schema.org/draft-07/schema#"))? -/// Defines schemas that maybe re-used within a complex JSON Schema document. -/// -/// definitions: Mapping? -/// Defines schemas that maybe re-used within a complex JSON Schema document. -/// -/// This is the same thing as [definitions], but was renamed in draft 2019. -/// -/// $defs: Mapping(availableAfter("https://json-schema.org/draft/2019-09/schema"))? -// endregion -// region Metadata - -/// A short descriptor of this schema. -/// -/// title: String? -/// A long descriptor of this schema. -/// -/// description: String? -/// A default instance value of this schema. -/// -/// This value is not used to fill in missing values during the validation process. -/// Non-validation tools such as documentation generators or form -/// generators may use this value to give hints to users about how to use -/// a value. -/// However, [default] is typically used to express that if a value is missing, -/// then the value is semantically the same as if the value was present with the -/// default value. -/// The value of [default] should validate against the schema in which it resides, -/// but that isn't required. -/// -/// default: JsonSchemaValue? -/// A place to provide a set of examples that validate against the schema. -/// -/// This isn't used for validation, but may help with explaining the effect -/// and purpose of the schema to a reader. -/// Each entry should validate against the schema in which it resides, but -/// that isn't strictly required. -/// There is no need to duplicate the [default] value in the [examples] array, -/// since [default] will be treated as another example. -/// -/// examples: JsonSchemaValue? -/// Indicates that the instance value should not be used and -/// may be removed in the future. -/// -/// Introduced in draft 2019-09. deprecated: Boolean(availableAfter("https://json-schema.org/draft/2019-09/schema"))? -/// Metadata indicating that the instance value should not be modified. -/// -/// It could be used to indicate that a `PUT` request that changes a value would result -/// in a 400 Bad Request response -/// -/// Introduced in draft 7. readOnly: Boolean(availableAfter("http://json-schema.org/draft-07/schema#"))? -/// Metadata indicating that a value may be set, but will remain hidden. -/// -/// In could be used to indicate you can set a value with a `PUT` request, -/// but it would not be included when retrieving that record with a `GET` request -/// -/// Introduced in draft 7. writeOnly: Boolean(availableAfter("http://json-schema.org/draft-07/schema#"))? -// endregion -// region Core validation - -/// The fundamental data type for a schema. -/// -/// At its core, JSON Schema defines the following basic types: -/// -/// - `string` -/// - `number` -/// - `integer` -/// - `boolean` -/// - `array` -/// - `object` -/// - `null` -/// -/// [type] may either be a string or a listing. -/// -/// - If it's a string, it is the name of one of the basic types above. -/// - If it is an array, it must be an array of strings, where each string -/// is the name of one of the basic types, and each element is unique. -/// In this case, the JSON snippet is valid if it matches *any* of the -/// given types. -/// -/// type: (JsonSchemaTypeName|Listing)? -/// Restricts the instance value to a fixed set of values. -/// -/// It must be a listing with at least one element, where each element is unique. -/// You can use [enum] even without a [type], to accept values of different types. -/// -/// Elements in the array might be of any value, including null. -/// enum: (*JsonSchemaValue|Listing)? -/// Restricts the instance value to a single value. -/// -/// `const`: JsonSchemaValue? -// endregion -// region Number validators - -/// Restricts the instance value to be a multiple of the given number. -/// -/// It may be set to any positive number. -/// -/// multipleOf: Number(isPositive)? -/// Restricts the instance value to be at minimum the given number. -/// -/// minimum: Number? -/// Restricts the instance value to be larger than the given number. -/// -/// exclusiveMinimum: Number? -/// Restricts the instance value to be at maximum the given number. -/// -/// maximum: Number? -/// Restricts the instance value to be smaller than the given number. -/// -/// exclusiveMaximum: Number? -// endregion -// region String validators - -/// Restricts the instance value to a regex pattern. -/// -/// The regular expression must conform to [ECMA 262](https://262.ecma-international.org/5.1/#sec/7.8.5). -/// -/// pattern: String(isRegex)? -/// Restricts the instance value's length to be at minimum the given number. -/// -/// minLength: UInt? -/// Restricts the instance value's length to be at maximum the given number. -/// -/// maxLength: UInt? -/// Allows for basic semantic validation on certain kinds of string values that are -/// commonly used. -/// -/// This allows values to be constrained beyond what the other tools in JSON Schema, -/// including Regular Expressions can do. -/// -/// format: ( "date-time" |"time" @@ -311,178 +110,50 @@ format: ( |"regex" |String)? -//endregion -// region Object validators - -/// The properties (key-value pairs) on the instance value. -/// -/// Each key is the name of a property and each value is a schema used to -/// validate that property. -/// Any property on the instance value that doesn't match any of the property -/// names within [properties] is ignored. -/// -/// properties: Mapping? -/// Specifies that properties on the instance value that match the specified -/// regular expression should conform to a certain schema. -/// -/// Sometimes you want to say that, given a particular kind of property name, -/// the value should match a particular schema. That's where -/// [patternProperties] comes in: it maps regular expressions to schemas. -/// If a property name matches the given regular expression, the property -/// value must validate against the corresponding schema. -/// -/// patternProperties: Mapping? -/// Controls the handling of any properties on the instance value that are -/// not listed within [properties], or match any of the regular expressions in -/// [patternProperties]. -/// -/// By default, any additional properties are allowed. -/// -/// Setting the [additionalProperties] to [false] means no additional -/// properties will be allowed. -/// -/// additionalProperties: Schema? -/// Properties that are required to exist on the instance value. -/// -/// By default, no properties are required. -/// -/// The `required` keyword takes an array of zero or more strings. Each -/// of these strings must be unique. -/// -/// required: Listing? -/// Validate that the property names match a schema. -/// -/// The [type] for the schema is implicitly `"string"`. -/// -/// propertyNames: Schema? -/// The minimum amount of properties that the instance value should have. -/// -/// minProperties: UInt? -/// The maximum amount of properties that the instance value should have. -/// -/// maxProperties: UInt? -// endregion -// region Array validators - -/// Constraints on items within an array. -/// -/// There are two ways in which arrays are generally used in JSON: -/// -/// - **List validation:** a sequence of arbitrary length where each -/// item matches the same schema. -/// -/// - **Tuple validation:** a sequence of fixed length where each item may -/// have a different schema. In this usage, the index (or location) of -/// each item is meaningful as to how the value is interpreted. (This -/// usage is often given a whole separate type in some programming -/// languages, such as Python's `tuple`). -/// -/// items: (*Schema|Listing)? -/// Controls whether it's valid to have additional items in a tuple beyond what is -/// defined in items. -/// -/// The value of the [additionalItems] is a schema that all additional items must pass -/// in order for the keyword to validate. -/// This is ignored if there is not a "tuple validation" items -/// keyword present in the same schema. -/// -/// additionalItems: Schema? -/// A schema that must match at least one item within the instance array. -/// -/// contains: Schema? -/// Constrains the instance value's length to be at minimum the given number. -/// -/// minItems: UInt? -/// Constrains the instance value's length to be at maximum the given number. -/// -/// maxItems: UInt? -/// Specifies that each item in the instance value is unique. -/// -/// uniqueItems: Boolean? -// endregion -// region Composition - -/// Specifies that the value must match against **exactly** one of the subschemas. -/// -/// oneOf: Listing(!isEmpty)? -/// Specifies that the value must match ay least one of the subschemas. -/// -/// anyOf: Listing(!isEmpty)? -/// Specifies that the value must match **all** of the subschemas. -/// -/// allOf: Listing(!isEmpty)? -/// The `not` keyword declares that an instance validates if it doesn't validate -/// against the given subschema. -/// -/// not: Schema? -/// The dependentRequired keyword conditionally requires that certain properties -/// must be present if a given property is present in an object -/// -/// dependentRequired: Mapping>? -/// The dependentSchemas keyword conditionally applies a subschema when a given property is present. -/// This schema is applied in the same way allOf applies schemas -/// -/// dependentSchemas: Mapping? -/// The `if`, `then` and `else` keywords allow the application of a subschema based on the outcome of another schema -/// If `if` is valid, `then` must also be valid (and `else` is ignored.) If `if` is invalid, `else` must also be valid (and `then` is ignored) -/// If `then` or `else` is not defined, `if` behaves as if they have a value of `true`. -/// -/// `if`: Schema? -/// If `then` and/or `else` appear in a schema without `if`, `then` and `else` are ignored. then: Schema? -/// If `then` and/or `else` appear in a schema without `if`, `then` and `else` are ignored. `else`: Schema? -// endregion - -/// Any additional properties that are [JsonSchema]. -/// -/// Additional properties do not affect the validation of the instance value, but -/// may be referred to using [$ref]. -/// -/// This is a child property because Pkl modules cannot express both known names -/// and arbitrary names. _inline_: Mapping? output { diff --git a/config/pkl/deps/pkl.experimental.uri/URI.pkl b/config/pkl/deps/pkl.experimental.uri/URI.pkl index 7db64df12..ab4dadd02 100644 --- a/config/pkl/deps/pkl.experimental.uri/URI.pkl +++ b/config/pkl/deps/pkl.experimental.uri/URI.pkl @@ -1,45 +1,18 @@ -//===----------------------------------------------------------------------===// -// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved. -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -//===----------------------------------------------------------------------===// -/// A Uniform Resource Identifier as defined by -/// [RFC-3986](https://datatracker.ietf.org/doc/html/rfc3986). -/// -/// [URI]s may be constructed literally, or parsed from a string via [parse]. @ModuleInfo { minPklVersion = "0.25.0" } module pkl.experimental.uri.URI import "URI.pkl" -/// The scheme component. scheme: String? -/// The user information portion of the authority component. userInfo: String? -/// The host portion of the authority component. host: String? -/// The port portion of the authority component. port: UInt16? -/// The path component, URI-encoded. -/// -/// Access the decoded form of the path via [pathSegments]. path: UriString = "" -/// The authority component of the URI. function authority(): String? = if (hasAuthority()) List( @@ -51,38 +24,26 @@ function authority(): String? = .join("") else null -/// The URI path split into its segments. -/// -/// Each segment is decoded. fixed pathSegments: List = let (parts = path.split("/").map((it) -> percentDecode(it))) if (hasAbsolutePath) parts.drop(1) else parts -/// The query component, URI-encoded. query: UriString? -/// The fragment component. fragment: String? -/// The base path portion of this URI. -/// -/// This equivalent to the current URI without its query and fragment components. hidden basePath: URI = (module) { query = null fragment = null } -/// Tells if this URI is an [absolute URI](https://datatracker.ietf.org/doc/html/rfc3986#section-4.3). hidden isAbsolute: Boolean = scheme != null -/// Tells if the [path] is absolute. hidden hasAbsolutePath: Boolean = path?.startsWith("/") ?? false -/// Tells if this URI has an [authority](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2). function hasAuthority(): Boolean = (userInfo ?? host ?? port) != null -// local function _removeDotSegments(input: List, result: List): List = if (input.isEmpty) result else @@ -98,7 +59,6 @@ local function removeDotSegments(input: String): String = _removeDotSegments(input.split("/"), List()).join("/") + if (input.endsWith("/")) "/" else "" -// local function mergePaths(base: URI, other: URI): String = if (other.hasAbsolutePath) other.path @@ -108,10 +68,6 @@ local function mergePaths(base: URI, other: URI): String = let (basePath = if (base.path.contains("/")) base.path.substring(0, base.path.lastIndexOf("/") + 1) else "/") removeDotSegments(basePath + other.path) -/// Resolves [other] as a URI reference to this URI. -/// -/// Follows the rules described in -/// [RFC-3986 Section 5.2](https://www.rfc-editor.org/rfc/rfc3986#section-5.2). function resolveUri(other: URI): URI = let (self = this) new { @@ -145,7 +101,6 @@ function resolveUri(other: URI): URI = fragment = other.fragment } -/// Resolves [other] as a URI string to this URI. function resolve(other: String): URI? = let (parsed = parse(other)) if (parsed == null) null @@ -161,48 +116,31 @@ function toString(): String = new Listing { when (fragment != null) { "#\(encode(fragment))" } }.join("") -/// Tells if [str] is a valid URI string. const local isUriString = (str: String) -> str .replaceAll(PERCENT_REGEX, "") .codePoints .every((it) -> isUriSafe(it)) -/// A string that has valid URI characters. typealias UriString = String(isUriString) -// alphanumeric or !#$&'()*+,-./:;=?@_~ const local function isUriSafe(codePoint: Int) = isAlphaNumeric(codePoint) - // ! || codePoint == 33 - // #$ || codePoint.isBetween(35, 36) - // &'()*+,-./ || codePoint.isBetween(38, 47) - // :; || codePoint.isBetween(58, 59) - // = || codePoint == 61 - // ?@ || codePoint.isBetween(63, 64) - // _ || codePoint == 95 - // ~ || codePoint == 126 -// alphanumeric or !'()*-._~ local function isUriComponentSafe(codePoint: Int) = isAlphaNumeric(codePoint) - // ! || codePoint == 33 - // '()* || codePoint.isBetween(39, 42) - // -. || codePoint.isBetween(45, 46) - // _ || codePoint == 95 - // ~ || codePoint == 126 local function getUtf8Bytes(codePoint: Int): List = @@ -227,13 +165,6 @@ local function getUtf8Bytes(codePoint: Int): List = 0x80.or(codePoint.and(0x3f)) ) -/// Encode into percent encoding into utf-8 bytes. -/// -/// Facts: -/// ``` -/// percentEncode(" ".codePoints.first) == "%20" -/// percentEncode("/".codePoints.first) == "%2F" -/// ``` local function percentEncode(codePoint: Int) = getUtf8Bytes(codePoint) .map((it) -> "%" + it.toRadixString(16).toUpperCase().padStart(2, "0")) @@ -241,12 +172,6 @@ local function percentEncode(codePoint: Int) = local hexDigits = "0123456789ABCDEF" -/// Facts: -/// ``` -/// getBytes("%20") == List(32) -/// getBytes("%7F") == List(127) -/// getBytes("%20%7F") == List(32, 127) -/// ``` local function getBytes(str: String): List = str .split("%") @@ -258,23 +183,10 @@ local function getBytes(str: String): List = ) const local function isAlphaNumeric(codePoint: Int) = - codePoint.isBetween(48, 57) // 0-9 - || codePoint.isBetween(65, 90) // a-z - || codePoint.isBetween(97, 122) // A-Z - -/// Encodes [str] using percent-encoding bytes to make it safe for the literal use as a URI. -/// -/// All characters except for alphanumeric chracters, and the chracters `!#$&'()*+,-./:;=?@_~` -/// are percent-encoded. -/// -/// Follows the rules for the `encodeURI` function as described by -/// [ECMA-262](https://262.ecma-international.org/5.1/#sec-15.1.3.3). -/// -/// Facts: -/// ``` -/// encode("https://example.com/some path/") == "https://example.com/some%20path" -/// ``` -/// + codePoint.isBetween(48, 57) + || codePoint.isBetween(65, 90) + || codePoint.isBetween(97, 122) + function encode(str: String): String = str.codePoints .map((codePoint) -> @@ -283,18 +195,6 @@ function encode(str: String): String = ) .join("") -/// Encodes [str] using percent-encoding to make it safe to literal use as a URI component. -/// -/// All characters except for alphanumeric characters, and the characters `-_.!~*'()` are -/// percent-encoded. -/// -/// Follows the rules for the `encodeURIComponent` function as described by -/// [ECMA-262](https://262.ecma-international.org/5.1/#sec-15.1.3.4). -/// -/// Facts: -/// ``` -/// encodeComponent("https://example.com/some path") == "https%3A%2F%2example.com%2Fsome%20path" -/// ``` function encodeComponent(str: String): String = str.codePoints .map((codePoint) -> @@ -305,7 +205,6 @@ function encodeComponent(str: String): String = const local PERCENT_REGEX = Regex(#"(?:%[\da-fA-F]{2})+"#) -/// Decodes [str] given a percent-encoded string. function percentDecode(str: String): String = str.replaceAllMapped(PERCENT_REGEX, (match) -> let (bytes = getBytes(match.value)) @@ -334,20 +233,14 @@ local function _doPercentDecode(bytes: List, ret: String) = let (b3 = bytes[3].and(0x3f)) _doPercentDecode(bytes.drop(4), ret + b0.or(b1).or(b2).or(b3).toChar()) -/// Regex to parse URI's. -/// -/// From . -// language=RegExp local URI_REGEX: Regex = Regex(#""" ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))? """#) -// language=RegExp local AUTHORITY_REGEX: Regex = Regex(#""" (?:([^@]+)@)?([^:]*)(?::(\d+))? """#) -// noinspection TypeMismatch function parseAuthority(authority: String): Dynamic = let (matches = AUTHORITY_REGEX.findMatchesIn(authority)) let (groups = matches[0].groups) @@ -357,9 +250,6 @@ function parseAuthority(authority: String): Dynamic = port = groups.getOrNull(3)?.value?.toInt() } -/// Parses the input string as a [URI]. -/// -/// If the input is not valid, returns `null`. function parse(str: String): URI? = let (matches = URI_REGEX.findMatchesIn(str)) if (matches.isEmpty) null diff --git a/config/pkl/renderers/claude-content.pkl b/config/pkl/renderers/claude-content.pkl index a987d9d1f..47d6493b0 100644 --- a/config/pkl/renderers/claude-content.pkl +++ b/config/pkl/renderers/claude-content.pkl @@ -205,16 +205,12 @@ exec "$@" """ } -/// Claude commands are intentionally thin. Each routes to exactly one composite -/// workflow skill, which owns all phases, waits, and final response rendering. commands { for (slug, workflow in workflowResults.workflows) { [slug] = workflowResults.renderCommand.apply(workflow, "allowed-tools: \(metadata.commandAllowedTools[slug])\n") } } -/// Claude has six command-routed workflow packages plus the standalone -/// decision-writing package used internally during synchronization. skillDocuments { for (path, document in workflowResults.skillDocuments.apply("compatibility: claude\n", "$ARGUMENTS", (_) -> "")) { [path] = document diff --git a/config/pkl/renderers/codex-content.pkl b/config/pkl/renderers/codex-content.pkl index cb4a14984..8e9d96f6c 100644 --- a/config/pkl/renderers/codex-content.pkl +++ b/config/pkl/renderers/codex-content.pkl @@ -5,19 +5,8 @@ import "common.pkl" as common import "codex-metadata.pkl" as metadata import "workflow-composite.pkl" as workflowResults -/// Current upstream Codex skill loading does not provide Claude/OpenCode-style -/// `$ARGUMENTS` substitution into skill Markdown, so Codex skill bodies name the -/// invocation input in prose instead of the literal, unsubstituted token. local codexArgumentsReference = "invocation input" -/// A concrete, runnable `$sce-{slug}` invocation example per catalog workflow, -/// appended to Codex's rendered `## Input` section alongside the prose above. -/// Codex's `/skills` UI and explicit `$sce-` invocation are the only ways -/// to reach these skills once `agents/openai.yaml` disables implicit invocation, -/// so the Input section states one concretely rather than only in the abstract. -/// Authored once here, directly against each workflow's own argument shape; -/// there is no cross-target canonical source for it, the same as the -/// `default_prompt` text in `codex-metadata.pkl`. local invocationExamplesBySkillSlug = new Mapping { ["sce-change-to-plan"] = "$sce-change-to-plan \"add dark mode to settings\"" ["sce-next-task"] = "$sce-next-task my-plan T03 approved" @@ -30,12 +19,6 @@ local invocationExamplesBySkillSlug = new Mapping { local invocationExampleForSkillSlug = (skillSlug: String) -> if (invocationExamplesBySkillSlug.containsKey(skillSlug)) invocationExamplesBySkillSlug[skillSlug] else "" -/// Codex has no command-routed entrypoints — it discovers skills directly, with -/// no per-target frontmatter beyond the shared description, matching Pi. Each -/// of the six catalog workflow skills additionally carries `agents/openai.yaml`, -/// disabling implicit invocation so these stateful lifecycle workflows are -/// reachable only via explicit `$sce-` invocation or `/skills` discovery. -/// `sce-decision` has no user-facing entrypoint on any target and is excluded. skillDocuments { for (path, document in workflowResults.skillDocuments.apply("", codexArgumentsReference, invocationExampleForSkillSlug)) { [path] = document diff --git a/config/pkl/renderers/codex-metadata.pkl b/config/pkl/renderers/codex-metadata.pkl index 3d3a51c34..84ae5016f 100644 --- a/config/pkl/renderers/codex-metadata.pkl +++ b/config/pkl/renderers/codex-metadata.pkl @@ -1,20 +1,3 @@ -// Typed Codex skill-interface metadata and the pure `agents/openai.yaml` -// renderer for the six catalog workflow skills, wired into -// `codex-content.pkl`'s exposed skill-document map. This module defines the -// model, the per-workflow authored values, and the render function, and also -// evaluates standalone. -// -// Confirmed upstream `agents/openai.yaml` schema -// (developers.openai.com/codex/skills, redirects to -// learn.chatgpt.com/docs/build-skills; confirmed 2026-08-24): three -// top-level sections — `interface` (`display_name`, `short_description`, -// `icon_small`, `icon_large`, `brand_color`, `default_prompt`, all -// optional), `policy.allow_implicit_invocation` (boolean, default `true`), -// and `dependencies.tools`. This module authors only -// `interface.{display_name,short_description,default_prompt}` and -// `policy.allow_implicit_invocation = false` — every catalog workflow is a -// stateful SCE lifecycle transition that must not auto-trigger from -// conversational relevance alone. import "../base/workflow-catalog.pkl" as catalog class CodexSkillMetadata { @@ -23,10 +6,6 @@ class CodexSkillMetadata { defaultPrompt: String } -/// `default_prompt` has no cross-target catalog counterpart (unlike -/// `display_name`/`short_description`, which reuse the catalog's -/// `title`/`description` verbatim); each value is authored once here as a -/// short imperative sentence describing what invoking the workflow does. local defaultPrompts: Mapping = new Mapping { ["change-to-plan"] = "Turn this change request into an SCE plan." ["next-task"] = "Review, approve, implement, verify, and synchronize the next SCE plan task." @@ -36,7 +15,6 @@ local defaultPrompts: Mapping = new Mapping { ["brownfield"] = "Reconstruct durable SCE context from this repository's own evidence." } -/// Keyed by `commandSlug`, matching `catalog.workflows`. metadataByCommandSlug: Mapping = new Mapping { for (slug, workflow in catalog.workflows) { [slug] = new CodexSkillMetadata { @@ -47,10 +25,6 @@ metadataByCommandSlug: Mapping = new Mapping { } } -/// Pure render: `interface` plus `policy.allow_implicit_invocation: false`, -/// no other top-level keys. Every value here is plain authored catalog text -/// with no YAML-special characters, so a double-quoted scalar needs no -/// general escaping helper. local render = (metadata: CodexSkillMetadata) -> """ interface: display_name: "\(metadata.displayName)" @@ -60,8 +34,6 @@ policy: allow_implicit_invocation: false """ -/// Rendered `agents/openai.yaml` text per catalog workflow command slug. -/// Evaluating this module standalone exercises every workflow's output. renderedByCommandSlug: Mapping = new Mapping { for (slug, metadata in metadataByCommandSlug) { [slug] = render.apply(metadata) diff --git a/config/pkl/renderers/generation-contract-check.pkl b/config/pkl/renderers/generation-contract-check.pkl index ecb7f58c5..84ec26a8a 100644 --- a/config/pkl/renderers/generation-contract-check.pkl +++ b/config/pkl/renderers/generation-contract-check.pkl @@ -6,9 +6,6 @@ import "pi-content.pkl" as pi import "codex-content.pkl" as codex import "codex-metadata.pkl" as codexMetadata -/// Build the expected inventory from each target's independently checked -/// document inventory plus the retained non-workflow assets. This deliberately -/// does not iterate `generate.pkl`'s output assembly. hidden expectedArtifactPaths = new Mapping { for (_, document in opencode.agents) { ["config/.opencode/agent/\(document.title).md"] = true @@ -125,10 +122,6 @@ local assertCodexHelperFailClosedMode = (artifacts: Mapping) -> ) "Codex hook helper: fail-closed PreToolUse mode plus the retained fail-open exec path" else throw("Codex hook helper must carry a fail-closed PreToolUse mode alongside the retained fail-open exec path") -/// Current upstream Codex skill loading provides no Claude/OpenCode-style -/// `$ARGUMENTS` substitution, so a literal, unsubstituted token in generated -/// Codex skill Markdown would be model-visible noise rather than the invoked -/// input. local assertCodexSkillsExcludeArguments = (artifacts: Mapping) -> if ( artifacts.every((path, text) -> @@ -138,11 +131,6 @@ local assertCodexSkillsExcludeArguments = (artifacts: Mapping) -> ) "Codex skills: no literal $ARGUMENTS in generated Markdown" else throw("generated Codex skill Markdown must not contain the literal token $ARGUMENTS") -/// Codex's `agents/openai.yaml` disables implicit invocation for the six -/// catalog workflows, so their SKILL.md `## Input` sections must each name a -/// concrete, own-slug `$sce-{slug}` invocation example alongside the -/// `invocation input` prose — the only way to reach these skills is `/skills` -/// discovery or explicit `$sce-` invocation. local assertCodexSkillInvocationExamples = (artifacts: Mapping) -> if ( expectedCodexMetadataArtifactPaths.every((_, slug) -> @@ -152,20 +140,12 @@ local assertCodexSkillInvocationExamples = (artifacts: Mapping) -> ) "Codex skill invocation examples: each Input section names its own $sce-{slug}" else throw("generated Codex SKILL.md must name a concrete $sce-{slug} invocation example in its Input section") -/// The six catalog workflows' generated `agents/openai.yaml` paths, keyed by -/// the catalog command slug so each can be checked against its own -/// catalog-derived `CodexSkillMetadata`. local expectedCodexMetadataArtifactPaths = new Mapping { for (slug, workflow in catalog.workflows) { ["config/.agents/skills/\(workflow.skillSlug)/agents/openai.yaml"] = slug } } -/// Every generated Codex `agents/openai.yaml` derives its `interface` values -/// from the shared workflow catalog and disables implicit invocation, since -/// each catalog workflow is a stateful SCE lifecycle transition that must not -/// auto-trigger from conversational relevance alone; `sce-decision` has no -/// user-facing entrypoint on any target and keeps no such file. local assertCodexSkillMetadataContract = (artifacts: Mapping) -> if ( expectedCodexMetadataArtifactPaths.every((path, slug) -> @@ -373,7 +353,6 @@ local compactWorkflowSlugs = new Listing { hidden isCompactWorkflowPath = (path: String) -> compactWorkflowSlugs.any((slug) -> path.endsWith("/skills/sce-\(slug)/SKILL.md")) -// This oracle intentionally does not read the production rendering helper. local expectedExecutionContract = (allowsDecision: Boolean) -> """ ## Execution contract @@ -461,10 +440,6 @@ local forbiddenUnscopedWorkflowTokens = new Listing { "not inter-skill handoffs" } -/// The five behaviors `/brownfield` cannot lose without becoming a different -/// workflow: the terminal bootstrap gate, the explicit documentation sweep, the -/// blocking confidence threshold, always-disclosed contradictions, and -/// additive-by-default writing with `rebuild` as the sole rewrite path. local requiredBrownfieldSkillTokens = new Listing { "### 1. Confirm the context root" "**Missing context bootstrap gate**" @@ -522,14 +497,6 @@ local forbiddenWorkflowReferenceTokens = new Listing { "references/validation-result.md" } -/// Six cross-target workflow packages, with package-local phase references and -/// supporting documents on the four phase-based workflows, plus the decision -/// package and retained non-workflow assets, across OpenCode, Claude, Pi, and -/// Codex, plus Codex's `.codex/hooks.json`, its install-guidance hook script, -/// and its six per-workflow `agents/openai.yaml` files (one per catalog -/// workflow, excluding `sce-decision`). Stating the total as a literal makes -/// an unintended inventory change fail here instead of silently becoming the -/// new expectation. local expectedArtifactPathCount = 145 local assertExactArtifactPaths = (actual: Mapping) -> @@ -741,11 +708,6 @@ local assertBrownfieldContent = (documents: Mapping) -> ) "generated brownfield package content: covers gate, evidence, confidence, contradictions, writes" else throw("generated sce-brownfield SKILL.md is missing a required bootstrap, documentation, confidence, contradiction, or write-mode rule") -/// Extract each fenced code block from `text`, fence markers included, so -/// callers can test a generated `SKILL.md` for a verbatim copy of a -/// `references/output.md` layout. Splitting on the triple-backtick fence -/// yields alternating outside/inside segments starting outside, so the -/// odd-indexed segments are exactly the fenced bodies. hidden fencedBlocksIn = (text: String) -> text.split("```").filterIndexed((index, _) -> index.isOdd).map((block) -> "```\(block)```") @@ -769,10 +731,6 @@ local assertOutputNotDuplicated = (documents: Mapping) -> ) "generated workflow SKILL.md documents: no output.md layout duplicated" else throw("generated SKILL.md reproduces a references/output.md fenced layout verbatim") -/// The manifest is the only carrier of optional-workflow identity outside Pkl, -/// so assert its content against the catalog rather than accepting whatever the -/// renderer emitted: every optional workflow appears with its catalog title and -/// slugs, and no core workflow appears at all. local assertOptionalWorkflowManifest = (artifacts: Mapping) -> let (text = artifacts["config/optional-workflows.json"]) if ( @@ -921,10 +879,6 @@ hidden assertNextTaskReportOwnership = (documents: Mapping) -> ) "sce-next-task report ownership: sync report is not duplicated in output.md" else throw("sce-next-task output.md must not duplicate the context-sync report contract") -/// Codex names the invocation input in prose instead of a literal `$ARGUMENTS` -/// (its harness does not substitute it), so exactly these two output-layout -/// references — the only ones quoting the received input back to the user — -/// legitimately diverge from Pi/Claude/OpenCode's text there. local codexArgumentDependentReferencePaths = new Listing { "sce-handover/references/output.md" "sce-brownfield/references/output.md" diff --git a/config/pkl/renderers/metadata-coverage-check.pkl b/config/pkl/renderers/metadata-coverage-check.pkl index 228feefb9..ced699068 100644 --- a/config/pkl/renderers/metadata-coverage-check.pkl +++ b/config/pkl/renderers/metadata-coverage-check.pkl @@ -21,8 +21,6 @@ local expectedWorkflowSkillByCommand = new Mapping { } } -/// Workflow packages render the package-local references owned by each -/// canonical workflow. Exact coverage rejects stale or missing references. local phaseReferencePathsByWorkflow = new Mapping { ["change-to-plan"] = new Listing { "references/context-load.md" @@ -65,9 +63,6 @@ local expectedSkillDocumentPaths = new Mapping { ["sce-decision/references/adr-template.md"] = true } -/// Codex additionally carries `agents/openai.yaml` for each of the six catalog -/// workflow skills, disabling implicit invocation; `sce-decision` has no -/// user-facing entrypoint on any target and keeps no such file. local expectedCodexSkillDocumentPaths = new Mapping { for (path, _ in expectedSkillDocumentPaths) { [path] = true @@ -125,8 +120,6 @@ local assertExactKeys = (actual: Mapping, expected: Mapping, label: String) -> ) "\(label): complete" else error("\(label) inventory does not match the canonical workflow matrix") -/// Routing is target-neutral: every collapsed target's command names exactly its -/// own workflow skill and no other. `target` labels which one is being checked. local assertCommandRoute = (target: String, slug: String, document: String) -> let (expectedInvocation = "Invoke the `\(expectedWorkflowSkillByCommand[slug])` skill exactly once") if ( @@ -158,8 +151,6 @@ inventoryChecks { ["codex-skill-documents"] = assertExactKeys.apply(codexSkillDocuments, expectedCodexSkillDocumentPaths, "Codex skill document") } -/// Force rendering after exact inventory checks so target-specific metadata -/// lookups and every nested package document are evaluated. opencodeAgentCoverage { for (slug, document in opencodeAgents) { [slug] = document.rendered diff --git a/config/pkl/renderers/opencode-content.pkl b/config/pkl/renderers/opencode-content.pkl index dcc1e745a..c7981bf69 100644 --- a/config/pkl/renderers/opencode-content.pkl +++ b/config/pkl/renderers/opencode-content.pkl @@ -10,9 +10,6 @@ local commandAgentLine = (slug: String) -> let (agentSlug = catalog.workflows[slug].openCodeAgentSlug) "agent: \"\(metadata.agentDisplayNames[agentSlug])\"\n" -/// One command declares one workflow skill as both its entry skill and its whole -/// skill chain. The skill owns every phase, so there is no sibling package to -/// hand off to. local commandSkillLines = (slug: String) -> let (skillSlug = catalog.workflows[slug].skillSlug) "entry-skill: \"\(skillSlug)\"\nskills:\n - \"\(skillSlug)\"\n" @@ -51,8 +48,6 @@ agents { } } -/// OpenCode commands are intentionally thin. Each routes to exactly one composite -/// workflow skill, which owns all phases, waits, and final response rendering. commands { for (slug, workflow in workflowResults.workflows) { [slug] = workflowResults.renderCommand.apply( @@ -62,10 +57,6 @@ commands { } } -/// OpenCode has six command-routed workflow packages plus the standalone -/// decision-writing package used internally during synchronization. Package- -/// relative paths stay flattened for deterministic generation, and only skill -/// entrypoints carry OpenCode-supported metadata. skillDocuments { for (path, document in workflowResults.skillDocuments.apply("compatibility: \(metadata.skillCompatibility)\n", "$ARGUMENTS", (_) -> "")) { [path] = document diff --git a/config/pkl/renderers/pi-content.pkl b/config/pkl/renderers/pi-content.pkl index d08f8661b..3454239ab 100644 --- a/config/pkl/renderers/pi-content.pkl +++ b/config/pkl/renderers/pi-content.pkl @@ -1,19 +1,12 @@ import "../base/decision-skill.pkl" as decision import "workflow-composite.pkl" as workflowResults -/// Pi prompts are intentionally thin. Each routes to exactly one composite -/// workflow skill, which owns all phases, waits, and final response rendering. -/// Pi prompts carry no target-specific frontmatter beyond the shared -/// description and argument hint. commands { for (slug, workflow in workflowResults.workflows) { [slug] = workflowResults.renderCommand.apply(workflow, "") } } -/// Pi has six prompt-routed workflow packages plus the standalone decision- -/// writing package used internally during synchronization, with no target- -/// specific skill frontmatter. skillDocuments { for (path, document in workflowResults.skillDocuments.apply("", "$ARGUMENTS", (_) -> "")) { [path] = document diff --git a/config/pkl/renderers/workflow-composite.pkl b/config/pkl/renderers/workflow-composite.pkl index edb6a7c0b..e00223074 100644 --- a/config/pkl/renderers/workflow-composite.pkl +++ b/config/pkl/renderers/workflow-composite.pkl @@ -7,10 +7,6 @@ import "../base/workflow-brownfield.pkl" as brownfield import "../base/workflow-catalog.pkl" as catalog import "../base/workflow-content.pkl" as model -/// A skill is the unit of durable control flow. Compose the canonical phase -/// packages into one workflow package instead of asking a command to transport -/// phase results between sibling skills. Composition is target-neutral: targets -/// differ only in the frontmatter lines their skills and commands support. class CompositeWorkflow { identity: catalog.WorkflowRecord slug: String = identity.commandSlug @@ -73,7 +69,6 @@ local renderInternalDocuments = (workflow: CompositeWorkflow) -> } }.join("\n\n") -/// Only handover uses the compact contract on this generic rendering path. local renderCompositePreamble = (workflow: CompositeWorkflow) -> if (workflow.slug == "handover") model.executionContract.apply("standard") @@ -104,14 +99,6 @@ local renderCompositePreamble = (workflow: CompositeWorkflow) -> \(model.helperSkillCompositionRule) """ -/// `extraFrontmatterLines` carries the target-specific frontmatter a skill -/// entrypoint supports. Each line ends with a newline; a target that adds none -/// passes the empty string. -/// The workflow's own `## Input`, `## Workflow`, and `## Rules` sit directly -/// under the skill title, so the document reads top to bottom with no wrapper -/// section between the preamble and the first instruction. A phase appendix is -/// emitted only for phases a module still lists; once every phase is stated at -/// the step that runs it, the listing is empty and no appendix heading renders. local renderSkill = (workflow: CompositeWorkflow, extraFrontmatterLines: String, argumentsReference: String, invocationExample: String) -> new model.WorkflowDocument { path = "SKILL.md" text = if (workflow.structuredSource.compositeSkillBody != null) @@ -147,9 +134,6 @@ local renderSkill = (workflow: CompositeWorkflow, extraFrontmatterLines: String, }.join("\n\n") } -/// `extraFrontmatterLines` carries the target-specific routing frontmatter a -/// command supports, under the same newline-terminated convention as -/// `renderSkill`. hidden renderCommand = (workflow: CompositeWorkflow, extraFrontmatterLines: String) -> new model.WorkflowDocument { path = workflow.command.path text = """ @@ -192,10 +176,6 @@ local commitWorkflow = new CompositeWorkflow { outputText = "" } -/// `sce-handover` invokes no sibling phase and waits for nothing mid-run, so its -/// base module already exposes one complete, mode-invariant output reference as -/// its sole `outputDocuments` entry; no additional composite-only header is -/// needed the way the phase-based workflows above need one. local handoverWorkflow = new CompositeWorkflow { identity = catalog.workflows["handover"] command = handover.workflow.command.document @@ -207,12 +187,6 @@ local handoverWorkflow = new CompositeWorkflow { }.join("\n\n") } -/// `sce-brownfield` is the second phase-free self-contained workflow, so like -/// `sce-handover` its base module already exposes one complete output reference -/// as its sole `outputDocuments` entry. It does wait mid-run, at the blocking -/// clarification gate, but the shared composite preamble's control-flow -/// paragraph already states that waits resume the same skill in the same -/// session, so no composite-only header is needed here either. local brownfieldWorkflow = new CompositeWorkflow { identity = catalog.workflows["brownfield"] command = brownfield.workflow.command.document @@ -233,12 +207,6 @@ workflows = new Mapping { [brownfieldWorkflow.slug] = brownfieldWorkflow } -/// Each target renders the same package-relative workflow documents and differs -/// only in the frontmatter its skill entrypoint carries, for a target whose -/// harness does not substitute `$ARGUMENTS` into skill Markdown the prose that -/// names the skill's invocation input, and, per workflow slug, an optional -/// concrete `$sce-{slug}` invocation example appended to `## Input` (empty for -/// a target that needs none). hidden skillDocuments = (extraSkillFrontmatterLines: String, argumentsReference: String, invocationExample: (String) -> String) -> new Mapping { for (_, workflow in workflows) { ["\(workflow.skillSlug)/SKILL.md"] = renderSkill.apply(workflow, extraSkillFrontmatterLines, argumentsReference, invocationExample.apply(workflow.skillSlug)) diff --git a/flake.nix b/flake.nix index 7cce1a470..c1ebf4d11 100644 --- a/flake.nix +++ b/flake.nix @@ -195,8 +195,6 @@ craneLib = (crane.mkLib pkgs).overrideToolchain (_: rustToolchain); - # Rust target triple for fully static musl Linux builds. - # null on non-Linux systems where the musl pipeline is never referenced. muslTarget = if pkgs.stdenv.isLinux then if pkgs.stdenv.hostPlatform.isAarch64 then @@ -208,13 +206,6 @@ else null; - # Per-target environment variables that tell cc-rs (and CMake) to - # compile C/C++ dependencies with the musl toolchain rather than the - # host glibc toolchain. Without these, native deps like aws-lc-sys - # and zstd-sys emit glibc symbols that musl cannot satisfy. - # Nix's musl gcc wrapper exposes target-prefixed binaries - # (e.g. x86_64-unknown-linux-musl-cc), not bin/cc. - # Use cc.targetPrefix to construct the correct path. muslEnvVars = let staticPkgs = pkgs.pkgsStatic; @@ -235,9 +226,6 @@ "-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0"; }; - # Separate toolchain that adds the musl target alongside the host target. - # Host-targeted checks (cli-tests, cli-clippy, cli-fmt) continue to use - # rustToolchain and are completely unaffected by this addition. rustToolchainMusl = pkgs.rust-bin.stable.${rustVersion}.default.override { extensions = [ "rustfmt" @@ -289,12 +277,6 @@ (pkgs.lib.fileset.maybeMissing ./cli/migrations) cliBuildInputFileset (pkgs.lib.fileset.maybeMissing ./cli/assets/hooks) - # The `mutation_trace::mbt` Quint Connect tests shell out to - # `quint run`/`quint test` against `../spec/*.qnt` (relative to - # the `cli/` crate root). `commonCargoSources` only covers Cargo - # package sources, so the top-level `spec/` tree must be listed - # explicitly or it never reaches the sandbox and every MBT test - # fails with an opaque "Quint returned non-zero code." (pkgs.lib.fileset.maybeMissing ./spec) ]; }; @@ -378,8 +360,6 @@ ]; }; - # Fixed-output derivation to fetch Bun dependencies - # The output hash must be updated when package.json or bun.lock changes configLibBashPolicyDeps = pkgs.stdenv.mkDerivation { pname = "config-lib-bash-policy-deps"; version = "0.1.0"; @@ -392,8 +372,6 @@ }; nativeBuildInputs = [ bunPackage ]; dontBuild = true; - # Shebang patching would embed the bash store path, breaking the - # fixed-output hash whenever bash changes. dontFixup = true; installPhase = '' bun install --frozen-lockfile --no-progress @@ -429,19 +407,10 @@ nativeBuildInputs = [ rustToolchain ]; }; - # Commit embedding is release-only: SCE_GIT_COMMIT is applied via - # releaseCommitArgs to the release derivations only. Keeping it out of - # commonCargoArgs means the native package, cargo tests, Clippy, and fmt - # stay commit-independent (cache-reusable across commits). releaseCommitArgs = { SCE_GIT_COMMIT = shortGitCommit; }; - # Produce the canonical Pkl payload before entering any Cargo - # derivation. The output is content-addressed by only the producer and - # its canonical generator inputs, so native, release, test, and Clippy - # builds share one handoff while dependency-only and formatting - # derivations remain independent of it. cliGeneratedInput = pkgs.runCommand "sce-cli-generated-input" { src = cliGeneratedInputSrc; @@ -489,7 +458,6 @@ src = craneLib.cleanCargoSource ./cli; }; - # Release consumers only need compiled dependencies, not check artifacts. cargoArtifacts = craneLib.buildDepsOnly ( cargoDepsArgs // { @@ -497,23 +465,11 @@ } ); - # Keep production artifacts on Crane's release profile. The test and - # Clippy derivations use the unoptimized Cargo test profile with a - # separate dependency cache, so changing CLI sources does not require - # repeatedly optimizing the entire Rust test binary. testProfileArgs = { CARGO_PROFILE = "test"; - # Smaller dependency artifacts for test/Clippy derivations. - # This uses the measured J variant (debug info disabled for all - # test-profile crates); Rust panic locations remain available. CARGO_PROFILE_TEST_DEBUG = "0"; }; - # The deps-only derivation must also prepare test/dev-dependency artifacts. - # The usual cargo build is redundant here: the checked targets are followed - # by cargo test --no-run during the check phase. - # Only test/Clippy vendoring removes the Turso kits' C ABI outputs. - # Native and release Cargo vendoring remains untouched. testCargoVendorDir = craneLib.vendorCargoDeps { cargoLock = ./cli/Cargo.lock; overrideVendorCargoPackage = package: drv: @@ -570,9 +526,6 @@ } ); - # Separate Crane pipeline that builds a fully static musl binary on Linux. - # On macOS this derivation is never referenced (sceReleasePackage selects - # scePackage), so the null muslTarget is harmless. cargoDepsArgsMusl = (cargoDepsArgs // muslEnvVars) // { @@ -598,8 +551,6 @@ scePackageMusl = craneLibMusl.buildPackage ( (commonCargoArgs // muslEnvVars // releaseCommitArgs) // { - # Crane expects cargoArtifacts rather than cargoArtifactsMusl. - # Reuse the separately prepared musl dependency artifacts. cargoArtifacts = cargoArtifactsMusl; nativeBuildInputs = [ rustToolchainMusl @@ -611,9 +562,6 @@ ]; CARGO_BUILD_TARGET = muslTarget; - # libloading (pulled by turso_core) emits `-ldl`, but musl has no - # separate libdl — the symbols live in libc. Provide a stub archive - # so the linker can satisfy `-ldl` without pulling in glibc. preBuild = '' mkdir -p /tmp/musl-dl-shim cat > /tmp/musl-dl-shim/dl.c <<'CEOF' @@ -631,12 +579,6 @@ } ); - # Native-toolchain release build for Darwin. Identical to scePackage - # except it embeds the real Git commit (SCE_GIT_COMMIT), so on macOS the - # release output reports the commit while native `.#sce` stays - # commit-independent. cargoArtifacts is deps-only and unaffected by - # SCE_GIT_COMMIT (only the cli crate's build.rs reads it), so it is - # shared with scePackage at no extra rebuild cost. sceReleasePackageNative = craneLib.buildPackage ( commonCargoArgs // releaseCommitArgs @@ -649,12 +591,8 @@ } ); - # Release package selection: static musl on Linux (fully static, no - # /nix/store runtime references), native-with-commit on macOS. sceReleasePackage = if pkgs.stdenv.isLinux then scePackageMusl else sceReleasePackageNative; - # Shared development tooling for the default shell. Excludes `scePackage` - # so `nix develop` does not compile the CLI; opt-in shells layer it back on. defaultDevShellPackages = (with pkgs; [ biome @@ -1661,10 +1599,6 @@ mkdir -p "$out" ''; - # Linux-only: audit the real static-musl release binary for forbidden - # /nix/store runtime references. Unlike nativePortabilityAuditCheck - # (a fixture-based unit test of the audit script), this inspects the - # actual sceReleasePackage binary. releasePortabilityAuditCheck = pkgs.runCommand "sce-release-portability-audit" { @@ -1701,9 +1635,6 @@ expectedVersion = version; }; - # The dedicated MBT runner is opt-in as a package, not a flake check: - # cli-tests already executes the same mutation_trace::mbt test module. - # The Quint workflow tests the spec separately, without rebuilding Rust MBT. mutationTraceQuintConnectCheck = craneLib.cargoTest ( testCargoArgs // { @@ -1752,11 +1683,6 @@ checks = { - # `mutation_trace::mbt` (the Quint Connect model-based-testing - # harness) is an ordinary `#[cfg(test)]` module reached by the - # full `cargo test` this check runs, so the pinned Quint binary - # must be on PATH for this check. The focused MBT runner is - # available separately as .#mutation-trace-quint-connect. cli-tests = craneLib.cargoTest ( testCargoArgs // { @@ -1938,8 +1864,6 @@ shellHook = defaultDevShellHook; }; - # Opt-in shell exposing the repository-built CLI as `sce` while keeping - # the default development shell fast. devShells.sce = pkgs.mkShell { packages = defaultDevShellPackages ++ [ scePackage ]; diff --git a/nix/flatpak/manifest.nix b/nix/flatpak/manifest.nix index ba7eb310e..9524eba92 100644 --- a/nix/flatpak/manifest.nix +++ b/nix/flatpak/manifest.nix @@ -49,9 +49,6 @@ let build-args = [ "--share=network" ]; env = { CARGO_HOME = "/run/build/sce/cargo"; - # The sandbox compiles a full repository checkout without Pkl, so - # build.rs must consume the staged cli/package-fallback payload - # instead of demanding a pre-generated handoff directory. SCE_CLI_PACKAGE_FALLBACK = "1"; }; }; diff --git a/nix/tests/npm-nixos-vm.nix b/nix/tests/npm-nixos-vm.nix index 7bec0e8db..231b603eb 100644 --- a/nix/tests/npm-nixos-vm.nix +++ b/nix/tests/npm-nixos-vm.nix @@ -17,8 +17,6 @@ let authenticityFailureMessage = "Release manifest authenticity check failed"; checksumFailureMessage = "Downloaded sce archive checksum mismatch"; - # Per-scenario paths; every scenario owns its own directory under - # ~/scenarios so installs, fixtures, and temp dirs never overlap. mkScenario = name: rec { dir = "${homeDir}/scenarios/${name}"; prefixDir = "${dir}/prefix"; @@ -85,8 +83,6 @@ let ''} ''; - # Runs as the test user with HOME, npm cache/config, and TMPDIR isolated - # under . asScenarioUser = scenarioDir: command: asUser '' @@ -97,7 +93,6 @@ let ${command} ''; - # Prepares the scenario's release fixture with the real binary. prepareScenarioFixture = scenario: asScenarioUser scenario.dir '' @@ -108,7 +103,6 @@ let --binary ${sceReleasePackage}/bin/sce 2>&1 ''; - # Starts the scenario's fixture server detached and waits for its port. startScenarioServer = scenario: asScenarioUser scenario.dir '' @@ -172,7 +166,6 @@ let echo "${label}: ${toString absentRuntimeTools} do not resolve on PATH=${path}" ''; - # Reruns postinstall in place against the scenario's fixture server. rebuildScenarioPackage = scenario: asScenarioUser scenario.dir '' diff --git a/npm/test/release-fixture.sh b/npm/test/release-fixture.sh index 719b6da5e..f0d3f37ac 100755 --- a/npm/test/release-fixture.sh +++ b/npm/test/release-fixture.sh @@ -1,15 +1,4 @@ #!/usr/bin/env bash -# Shared hermetic release-fixture harness for npm package tests. -# -# Sourced as a library (pack-smoke.sh, VM scenarios, release canary) or run -# directly: -# -# release-fixture.sh prepare [--package-dir | --tarball ] -# [--binary ] -# release-fixture.sh serve [--port-file ] -# -# The fixture swaps a throwaway signing key into the staged package and -# repacks it, so it never proves the exact release artifact or production key. set -euo pipefail FIXTURE_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -51,8 +40,6 @@ fixture_assert_launcher_mode() { fixture_log "packed $FIXTURE_LAUNCHER_ENTRY mode $launcher_mode" } -# Stages package contents into from a packed tarball (asserting its -# launcher mode first) or, when is empty, from . fixture_stage_package() { local stage_dir="$1" local package_dir="$2" @@ -69,8 +56,6 @@ fixture_stage_package() { rm -rf "$stage_dir/runtime" "$stage_dir/node_modules" } -# Sets FIXTURE_VERSION and FIXTURE_TARGET_{TRIPLE,OS,ARCH} from the staged -# package.json and the package's own platform resolution. fixture_resolve_platform() { local stage_dir="$1" local platform_json @@ -89,8 +74,6 @@ fixture_resolve_platform() { FIXTURE_TARGET_ARCH="$(node -p "JSON.parse(process.argv[1]).arch" "$platform_json")" } -# Generates a throwaway manifest signing key (its public half replaces the -# staged package key) and a self-signed loopback TLS certificate. fixture_generate_keys() { local stage_dir="$1" local keys_dir="$2" @@ -110,8 +93,6 @@ fixture_generate_tls_cert() { -keyout "$keys_dir/tls-key.pem" -out "$keys_dir/tls-cert.pem" 2>/dev/null } -# Builds the canonical archive (stub binary, or when given), its -# checksum, and the signed release manifest in . fixture_build_release() { local release_dir="$1" local keys_dir="$2" @@ -169,8 +150,6 @@ EOF openssl base64 -A >"$release_dir/$manifest_name.sig" } -# Packs into , asserts the launcher mode, and sets -# FIXTURE_TARBALL. fixture_pack() { local stage_dir="$1" local pack_dir="$2" @@ -181,9 +160,6 @@ fixture_pack() { fixture_assert_launcher_mode "$FIXTURE_TARBALL" } -# Starts fixture-release-server.mjs in the background, waits for its port -# file, and sets FIXTURE_SERVER_PID and FIXTURE_PORT. Callers own cleanup via -# fixture_serve_stop. fixture_serve_start() { local release_dir="$1" local keys_dir="$2" @@ -215,8 +191,6 @@ fixture_serve_stop() { fi } -# Installs into offline against the loopback fixture -# server at , trusting ; npm cache/config live in . fixture_npm_install() { local prefix_dir="$1" local tarball="$2" @@ -238,8 +212,6 @@ fixture_npm_install() { fixture_fail "npm install of the packed tarball failed." } -# Asserts the installed runtime/sce mode and the .bin/sce symlink target, and -# sets FIXTURE_SCE_BIN. fixture_assert_install_layout() { local prefix_dir="$1" local installed_dir="$prefix_dir/$FIXTURE_INSTALLED_PACKAGE_DIR" diff --git a/packaging/flatpak/sce-flatpak.sh b/packaging/flatpak/sce-flatpak.sh index 372a64086..997afd238 100755 --- a/packaging/flatpak/sce-flatpak.sh +++ b/packaging/flatpak/sce-flatpak.sh @@ -77,7 +77,6 @@ ensure_flatpak_user_remote() { } substitute_placeholder() { - # Streams a template, replacing every occurrence of $1 with literal $2. awk -v ph="$1" -v val="$2" \ 'BEGIN { len = length(ph) } { @@ -148,7 +147,6 @@ generate_release_manifest() { printf '%s/%s\n' "${out_dir}" "${MANIFEST_NAME}" } -# Constrained inputs (semver, hex SHA, fixed filenames, x86_64/aarch64) — no JSON escaping needed. emit_source_manifest_metadata() { local path="$1" version="$2" release_commit="$3" package_name="$4" checksum_name="$5" checksum="$6" cat > "${path}" < { attempts.get(id).status != Rejected or not(evidenceAttempts.contains(id)) }) @@ -1468,7 +1449,6 @@ module mutation_cursor { attempts.get(id).status == Rejected }) - // Cheap, quantifier-shallow invariants over WORKTREES/SCOPES/ATTEMPTS. val SafetyCore = and { CursorRevisionConsistent, FailureKindMatchesTaint, @@ -1484,11 +1464,6 @@ module mutation_cursor { RejectedAttemptsDoNotCommitEvidence, } - // Uniqueness and cross-referencing checks over the growing history logs - // (mutationEvents, cursorHistory, protocolHistory, scopeHistory, - // abandonHistory, recoveryHistory). These are the most expensive conjuncts to verify since - // their cost scales with trace depth, so they are split out to be checked - // in their own CI job rather than serialized with the rest of Safety. val SafetyHistory = and { MutationEventUniquePerWorktreeRevision, CursorHistoryUniquePerWorktreeRevision, @@ -1503,7 +1478,6 @@ module mutation_cursor { RecoveryClearsExternalTaintOnlyAfterBaseline, } - // Attribution and scope-start semantics. val SafetyAttribution = and { AttributionMatchesObservedScopes, AiExclusiveRequiresExactlyOneActiveScope, @@ -2242,12 +2216,6 @@ module mutation_cursor { .expect(scopes.get(Scope3).status == Abandoned) .expect(Safety) - // Non-default-values smoke scenario for the Rust MBT driver (T04): proves - // that a worktree/tree/attempt/boundary combination other than the - // WT0/Tree0-Tree1/Attempt0/Flush(WT0) defaults used throughout the runs - // above is transported end to end. `#[quint_test]` replays this exact - // scenario through `protocol::prepare`/`protocol::commit` and compares the - // resulting Rust state against the state asserted below. run testMbtDriverTransportsNonDefaultArguments = init .then(mutate(WT1, Tree3)) @@ -2258,15 +2226,6 @@ module mutation_cursor { .expect(attempts.get(Attempt5).status == Committed) .expect(Safety) - // Guarded-no-op regression: re-preparing Attempt0 after - // it is already Prepared hits `prepare`'s guarded branch - // (`attempts.get(attempt).status != Available`), which must still record - // `MbtPrepare({attempt: Attempt0, boundary: Advance(...)})` — the second - // call's own operation and arguments — rather than falling through to - // `MbtStutter`. `#[quint_test]` replays this through the real - // `protocol::prepare`, proving the Rust driver calls it a second time - // (never skipping the call because Quint's semantic state is unchanged) - // and independently reaches the same no-op outcome. run testMbtGuardedPrepareInvokesRealPrepare = init .then(prepare(Attempt0, Start({ scope: Scope0, event: Event0 }))) @@ -2275,13 +2234,6 @@ module mutation_cursor { .expect(attempts.get(Attempt0).boundary == Start({ scope: Scope0, event: Event0 })) .expect(Safety) - // Guarded-no-op regression: `recover(WT0)` on a worktree - // that is neither tainted, externally tainted, nor needing rebaseline hits - // `recover`'s guarded branch, which must still record - // `MbtRecover({worktree: WT0})` rather than `MbtStutter`. `#[quint_test]` - // replays this through the real `protocol::recover`, proving the Rust - // driver calls it (never skipping the call) and independently reaches the - // same no-op outcome. run testMbtGuardedRecoverInvokesRealRecover = init .then(recover(WT0))