scc_engine/
ops.rs

1//! Universal operation registry (spec §§6-8): every SCC capability
2//! gets a stable operation ID; `engine.operations().list()` explains the
3//! API and `engine.invoke(id, input)` executes it. Typed namespaces
4//! (`engine.context().task(..)`) and dynamic invoke share ONE
5//! implementation — there are never two paths to the same behavior.
6
7use serde::{Deserialize, Serialize};
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
10// trace:exempt reason=internal-detail
11pub enum MutationClass {
12    Read,
13    Write,
14    Watch,
15}
16
17#[derive(Debug, Clone, Serialize, Deserialize)]
18// trace:exempt reason=internal-detail
19pub struct OperationDescriptor {
20    pub id: &'static str,
21    pub description: &'static str,
22    pub mutation: MutationClass,
23    pub streaming: bool,
24}
25
26// trace:exempt reason=internal-detail
27pub const OPERATIONS: &[OperationDescriptor] = &[
28    // workspace
29    OperationDescriptor { id: "workspace.init", description: "Initialize the SCC workspace (.scc/config.yaml + database)", mutation: MutationClass::Write, streaming: false },
30    OperationDescriptor { id: "workspace.status", description: "Index status, stats, and freshness", mutation: MutationClass::Read, streaming: false },
31    OperationDescriptor { id: "workspace.session", description: "Pin the current model session (repo, revision, epoch, config, plugins, salt)", mutation: MutationClass::Read, streaming: false },
32    OperationDescriptor { id: "workspace.session_check", description: "Check a pinned session against live state (current vs stale)", mutation: MutationClass::Read, streaming: false },
33    OperationDescriptor { id: "workspace.state_path", description: "Print the SCC state directory", mutation: MutationClass::Read, streaming: false },
34    OperationDescriptor { id: "workspace.languages", description: "Generated language-support matrix", mutation: MutationClass::Read, streaming: false },
35    // index
36    OperationDescriptor { id: "index.full", description: "Index the repository (cold on first run, incremental afterwards)", mutation: MutationClass::Write, streaming: false },
37    OperationDescriptor { id: "index.refresh", description: "Refresh selected paths", mutation: MutationClass::Write, streaming: false },
38    OperationDescriptor { id: "index.status", description: "Alias for workspace.status", mutation: MutationClass::Read, streaming: false },
39    // resolution
40    OperationDescriptor { id: "resolution.run", description: "Run semantic resolution, then recompile the derived layer", mutation: MutationClass::Write, streaming: false },
41    // graph
42    OperationDescriptor { id: "graph.recompile", description: "Recompile the derived graph layer", mutation: MutationClass::Write, streaming: false },
43    OperationDescriptor { id: "graph.search", description: "FTS entity search with LIKE fallback (alias for graph.query entities half)", mutation: MutationClass::Read, streaming: false },
44    OperationDescriptor { id: "graph.search_symbols", description: "FTS symbol search with LIKE fallback (alias for graph.query symbols half)", mutation: MutationClass::Read, streaming: false },
45    OperationDescriptor { id: "graph.entity.get", description: "Fetch one entity by id", mutation: MutationClass::Read, streaming: false },
46    OperationDescriptor { id: "graph.entities", description: "List components/entities", mutation: MutationClass::Read, streaming: false },
47    OperationDescriptor { id: "graph.relationships", description: "Query relationships", mutation: MutationClass::Read, streaming: false },
48    OperationDescriptor { id: "graph.query", description: "Lexical entity/symbol search with substring fallback", mutation: MutationClass::Read, streaming: false },
49    OperationDescriptor { id: "graph.flows", description: "List flows", mutation: MutationClass::Read, streaming: false },
50    // context
51    OperationDescriptor { id: "context.overview", description: "Startup capsule / system overview", mutation: MutationClass::Read, streaming: false },
52    OperationDescriptor { id: "context.atlas", description: "Full System Atlas", mutation: MutationClass::Read, streaming: false },
53    OperationDescriptor { id: "context.startup", description: "Atlas + Surface fusion for session startup", mutation: MutationClass::Write, streaming: false },
54    OperationDescriptor { id: "context.task", description: "Complete task artifact (pack + surface delta)", mutation: MutationClass::Write, streaming: false },
55    OperationDescriptor { id: "context.task_pack", description: "Enriched task pack only (no delta, no ledger)", mutation: MutationClass::Read, streaming: false },
56    OperationDescriptor { id: "context.subagent", description: "Narrower bounded task pack for delegated agents", mutation: MutationClass::Read, streaming: false },
57    OperationDescriptor { id: "context.component", description: "Context pack for one component", mutation: MutationClass::Read, streaming: false },
58    OperationDescriptor { id: "context.flow", description: "Context pack for one flow", mutation: MutationClass::Read, streaming: false },
59    OperationDescriptor { id: "context.impact", description: "Impact analysis pack", mutation: MutationClass::Read, streaming: false },
60    OperationDescriptor { id: "context.verify", description: "Freshness/evidence verification pack", mutation: MutationClass::Read, streaming: false },
61    OperationDescriptor { id: "context.external_docs", description: "External dependency docs via the configured Context7 command", mutation: MutationClass::Read, streaming: false },
62    OperationDescriptor { id: "context.structural", description: "Structural Source representation", mutation: MutationClass::Read, streaming: false },
63    OperationDescriptor { id: "context.compress", description: "Compress a task pack", mutation: MutationClass::Read, streaming: false },
64    // surface + ranking
65    OperationDescriptor { id: "surface.build", description: "System Surface Map (global or task-personalized)", mutation: MutationClass::Write, streaming: false },
66    OperationDescriptor { id: "ranking.important", description: "Fast where-to-pay-attention answer", mutation: MutationClass::Read, streaming: false },
67    OperationDescriptor { id: "ranking.symbols", description: "Full blend per symbol with feature decomposition + plugin hooks", mutation: MutationClass::Read, streaming: false },
68    OperationDescriptor { id: "ranking.global", description: "Alias for ranking.symbols (global blend, no goal)", mutation: MutationClass::Read, streaming: false },
69    OperationDescriptor { id: "ranking.task", description: "Alias for ranking.symbols (task-personalized blend)", mutation: MutationClass::Read, streaming: false },
70    OperationDescriptor { id: "ranking.entities", description: "Alias for ranking.symbols (entity-ranked blend)", mutation: MutationClass::Read, streaming: false },
71    OperationDescriptor { id: "ranking.candidates", description: "Lexical candidate generation (stage 1)", mutation: MutationClass::Read, streaming: false },
72    OperationDescriptor { id: "ranking.pagerank.global", description: "Raw global PageRank vector over the heterogeneous universe", mutation: MutationClass::Read, streaming: false },
73    OperationDescriptor { id: "ranking.pagerank.task", description: "Raw task-personalized PPR vector", mutation: MutationClass::Read, streaming: false },
74    OperationDescriptor { id: "ranking.final_importance", description: "Pure blend function over explicit features", mutation: MutationClass::Read, streaming: false },
75    OperationDescriptor { id: "ranking.edge_weight", description: "Pure edge-weight function", mutation: MutationClass::Read, streaming: false },
76    OperationDescriptor { id: "ranking.architectural_specificity", description: "Architectural specificity (exported/public signals)", mutation: MutationClass::Read, streaming: false },
77    OperationDescriptor { id: "ranking.explain", description: "Rank explanation for one symbol", mutation: MutationClass::Read, streaming: false },
78    OperationDescriptor { id: "selection.mmr", description: "MMR diversification over a ranked list", mutation: MutationClass::Read, streaming: false },
79    OperationDescriptor { id: "selection.quotas", description: "Token-fraction quota selection over ranked rows", mutation: MutationClass::Read, streaming: false },
80    OperationDescriptor { id: "selection.budget", description: "Value/token budget selection", mutation: MutationClass::Read, streaming: false },
81    // source
82    OperationDescriptor { id: "source.structural", description: "Alias for context.structural", mutation: MutationClass::Read, streaming: false },
83    // embeddings (optional semantic ranker)
84    OperationDescriptor { id: "embeddings.build", description: "Compute and store entity embeddings with the configured model", mutation: MutationClass::Write, streaming: false },
85    OperationDescriptor { id: "embeddings.get", description: "Fetch the stored embedding vector for one entity", mutation: MutationClass::Read, streaming: false },
86    OperationDescriptor { id: "embeddings.status", description: "Stored embedding count", mutation: MutationClass::Read, streaming: false },
87    // evidence
88    OperationDescriptor { id: "evidence.get", description: "Fetch one evidence record by id", mutation: MutationClass::Read, streaming: false },
89    OperationDescriptor { id: "evidence.list", description: "List evidence records, optionally filtered by path", mutation: MutationClass::Read, streaming: false },
90    // runtime
91    OperationDescriptor { id: "runtime.ingest", description: "Ingest runtime evidence", mutation: MutationClass::Write, streaming: false },
92    OperationDescriptor { id: "runtime.status", description: "Runtime observation status", mutation: MutationClass::Read, streaming: false },
93    OperationDescriptor { id: "runtime.reconcile", description: "Static-vs-observed reconciliation", mutation: MutationClass::Read, streaming: false },
94    OperationDescriptor { id: "runtime.signatures", description: "Trace-path signatures recorded during OTLP ingest", mutation: MutationClass::Read, streaming: false },
95    // architecture
96    OperationDescriptor { id: "architecture.components", description: "Alias for graph.entities", mutation: MutationClass::Read, streaming: false },
97    OperationDescriptor { id: "architecture.flows", description: "Alias for graph.flows", mutation: MutationClass::Read, streaming: false },
98    OperationDescriptor { id: "architecture.invariants", description: "Structural invariant checks", mutation: MutationClass::Read, streaming: false },
99    OperationDescriptor { id: "architecture.drift", description: "Architectural drift findings", mutation: MutationClass::Read, streaming: false },
100    OperationDescriptor { id: "architecture.cochange", description: "Git co-change pairs", mutation: MutationClass::Read, streaming: false },
101    // history / snapshots / checkpoints
102    OperationDescriptor { id: "history.revisions", description: "Graph revision history", mutation: MutationClass::Read, streaming: false },
103    OperationDescriptor { id: "history.diff", description: "Semantic diff between revisions", mutation: MutationClass::Read, streaming: false },
104    OperationDescriptor { id: "snapshot.save", description: "Save a task snapshot", mutation: MutationClass::Write, streaming: false },
105    OperationDescriptor { id: "snapshot.get", description: "Show a snapshot artifact", mutation: MutationClass::Read, streaming: false },
106    OperationDescriptor { id: "snapshot.diff", description: "Diff a snapshot against current", mutation: MutationClass::Read, streaming: false },
107    OperationDescriptor { id: "checkpoint.save", description: "Capture session checkpoint", mutation: MutationClass::Write, streaming: false },
108    OperationDescriptor { id: "checkpoint.load", description: "Load session checkpoint", mutation: MutationClass::Read, streaming: false },
109    // systems / imports / exports
110    OperationDescriptor { id: "system.stitch", description: "Multi-repo stitch (routes/topics/exports)", mutation: MutationClass::Read, streaming: false },
111    OperationDescriptor { id: "import.scip", description: "Import external evidence (SCIP/CCG/GitNexus/Beads...)", mutation: MutationClass::Write, streaming: false },
112    OperationDescriptor { id: "import.ccg", description: "Alias for import.scip format=ccg", mutation: MutationClass::Write, streaming: false },
113    OperationDescriptor { id: "import.gitnexus", description: "Alias for import.scip format=gitnexus", mutation: MutationClass::Write, streaming: false },
114    OperationDescriptor { id: "import.tracelayer", description: "Alias for import.scip format=tracelayer", mutation: MutationClass::Write, streaming: false },
115    OperationDescriptor { id: "import.beads", description: "Alias for import.scip format=beads", mutation: MutationClass::Write, streaming: false },
116    OperationDescriptor { id: "import.hindsight", description: "Alias for import.scip format=hindsight", mutation: MutationClass::Write, streaming: false },
117    OperationDescriptor { id: "import.cbm", description: "Alias for import.scip format=cbm", mutation: MutationClass::Write, streaming: false },
118    OperationDescriptor { id: "export.system_ir", description: "Export System IR (json/jsonl/ccg/flow-graphs)", mutation: MutationClass::Read, streaming: false },
119    OperationDescriptor { id: "model.get", description: "Complete live model: repository, epoch, files, entities, relationships, evidence, components, flows, invariants, stats", mutation: MutationClass::Read, streaming: false },
120    OperationDescriptor { id: "export.system_ir_jsonl", description: "Alias for export.system_ir format=system-ir.jsonl", mutation: MutationClass::Read, streaming: false },
121    OperationDescriptor { id: "export.ccg", description: "Alias for export.system_ir format=ccg", mutation: MutationClass::Read, streaming: false },
122    OperationDescriptor { id: "export.flow_graphs", description: "Alias for export.system_ir format=flow-graphs.json", mutation: MutationClass::Read, streaming: false },
123    OperationDescriptor { id: "export.diagram", description: "Architecture diagram (mermaid|svg) with node/edge/flow counts", mutation: MutationClass::Read, streaming: false },
124    OperationDescriptor { id: "export.snap", description: "Alias for export.system_ir format=capsule.md", mutation: MutationClass::Read, streaming: false },
125    // integrity / integrations / lessons / setup
126    OperationDescriptor { id: "integrity.invariants", description: "Alias for architecture.invariants", mutation: MutationClass::Read, streaming: false },
127    OperationDescriptor { id: "integrity.ci", description: "CI gate over drift severity", mutation: MutationClass::Read, streaming: false },
128    OperationDescriptor { id: "integrations.list", description: "Configured adapters with capability scope", mutation: MutationClass::Read, streaming: false },
129    OperationDescriptor { id: "integrations.doctor", description: "Offline adapter diagnostics", mutation: MutationClass::Read, streaming: false },
130    OperationDescriptor { id: "integrations.describe", description: "Describe one integration adapter by name", mutation: MutationClass::Read, streaming: false },
131    OperationDescriptor { id: "lessons.add", description: "Append a hindsight lesson", mutation: MutationClass::Write, streaming: false },
132    OperationDescriptor { id: "lessons.list", description: "List hindsight lessons", mutation: MutationClass::Read, streaming: false },
133    OperationDescriptor { id: "beads.list", description: "List active bead tasks", mutation: MutationClass::Read, streaming: false },
134    OperationDescriptor { id: "plugins.list", description: "List enabled plugins with lock entries", mutation: MutationClass::Read, streaming: false },
135    OperationDescriptor { id: "plugins.describe", description: "Describe one plugin manifest", mutation: MutationClass::Read, streaming: false },
136    OperationDescriptor { id: "plugins.doctor", description: "Plugin environment + failure diagnostics", mutation: MutationClass::Read, streaming: false },
137    OperationDescriptor { id: "plugins.invoke", description: "Invoke any plugin operation explicitly", mutation: MutationClass::Write, streaming: false },
138    OperationDescriptor { id: "plugins.lock", description: "Write .scc/plugins.lock from the live plugin set", mutation: MutationClass::Write, streaming: false },
139    OperationDescriptor { id: "plugins.check", description: "Verify live plugins against .scc/plugins.lock", mutation: MutationClass::Read, streaming: false },
140    OperationDescriptor { id: "plugins.contribute", description: "Validate and commit a plugin contribution batch (entities, relationships, evidence)", mutation: MutationClass::Write, streaming: false },
141    OperationDescriptor { id: "plugin_state.get", description: "Read one namespaced plugin state key (StateRead grant)", mutation: MutationClass::Read, streaming: false },
142    OperationDescriptor { id: "plugin_state.put", description: "Write one namespaced plugin state key (StateWrite grant)", mutation: MutationClass::Write, streaming: false },
143    OperationDescriptor { id: "plugin_state.delete", description: "Delete one namespaced plugin state key (StateWrite grant)", mutation: MutationClass::Write, streaming: false },
144    OperationDescriptor { id: "plugin_state.scan", description: "Scan namespaced plugin state keys by prefix (StateRead grant)", mutation: MutationClass::Read, streaming: false },
145];
146
147// trace:exempt reason=internal-detail
148pub fn describe(id: &str) -> Option<&'static OperationDescriptor> {
149    OPERATIONS.iter().find(|d| d.id == id)
150}
151
152// trace:exempt reason=internal-detail
153pub fn ids() -> Vec<&'static str> {
154    OPERATIONS.iter().map(|d| d.id).collect()
155}
156
scc_engine/ops.rs

scc_engine/
ops.rs
