title: "Ohm — product specification" description: "The top-level spec: what Ohm is, the decisions that shape it, and the map of the per-feature specs." nodes: 33 progress: 88% generated: ohm spec editor#

Ohm — product specification#

The top-level spec: what Ohm is, the decisions that shape it, and the map of the per-feature specs.

Contents#

☑ What Ohm is#

☑ A browser first#

requirement

Ohm opens on a web page. Tabs, an omnibox, history and navigation behave the way a browser behaves, because everything else in the product assumes you are already looking at the web.

What it adds: tabs that can be hidden and keep working, a language built in, and projects that collect what you find.

  • spec: 01-engine-and-shell

☑ A language, not a plugin API#

requirement

Automation and AI work is written in Ohm: Lua 5.4 with LaTeX math, where $\frac{22}{7}$ is an expression and \CoT_{\Psi}(q; C) is a call into a reasoning operator. Scripts are plain files in a folder the user owns.

  • spec: 02-ohm-language
  • spec: 03-scripts

☑ Local by default#

requirement

Model profiles cover hosted APIs, a local Ollama, an embedded llama.cpp and in-browser models on WebGPU. Credentials are encrypted by the OS and never reach the UI or a script. Nothing is uploaded that the user did not send.

  • spec: 04-models-and-settings

☑ Work is kept as files#

requirement

Projects, prompts, experiments, curves, graphs, specs, documents and annotations are all plain files under one folder — readable by hand, by scripts and by git.

  • spec: 12-storage
  • spec: 08-projects-and-research

☑ Decisions that shape everything#

☑ The engine is replaceable#

decision

Electron today, a Chromium fork later. One package defines the interfaces, exactly one package may import electron, and a build-time check enforces it.

  • spec: 01-engine-and-shell

☑ Compile, do not interpret twice#

decision

Ohm compiles to Lua line for line, so a runtime error names the .ohm line with no source map. Graphs compile to Ohm scripts rather than executing themselves, so there is exactly one execution engine and the generated code can be read and edited.

  • spec: 02-ohm-language
  • spec: 09-graphs

☑ Every long-running thing can be stopped#

decision

Scripts run in a worker thread that can be terminated even mid-CPU-loop; downloads abort; experiments cancel between cases. The one gap is model generation, which no provider currently lets us cancel.

  • spec: 02-ohm-language
  • spec: 06-experiments

☑ Validate paths at one choke point#

decision

Ids, item names and every user-supplied relative path pass through a single containment check before becoming a filesystem path, and the custom URL schemes apply the same rule at the request level.

  • spec: 08-projects-and-research
  • spec: 01-engine-and-shell

☑ Feature map#

☑ Engine seam and browser shell#

reference

Tabs, hidden tabs, schemes, the UI↔core protocol, automation.

  • spec: 01-engine-and-shell

☑ The Ohm language#

reference

Syntax, compilation, the runtime, the host API and the operator families.

  • spec: 02-ohm-language

☑ Scripts#

reference

The scripts folder, explorer, editor, console and run lifecycle.

  • spec: 03-scripts

☑ Models, settings and credentials#

reference

Five providers, OS-encrypted secrets, the models folder, Hugging Face.

  • spec: 04-models-and-settings

☑ Prompt management#

reference

Versioned templates with typed variables and a playground.

  • spec: 05-prompts

☑ Experiment management#

reference

Datasets × sweeps × profiles, evaluators, runs and statistics.

  • spec: 06-experiments

☑ Curves and typed variables#

reference

Piecewise curves, a safe expression language, typed outputs, sweeps.

  • spec: 07-curves

☑ Projects and deep research#

reference

Project storage, links, templates and the research pipeline.

  • spec: 08-projects-and-research

☑ Graph editor#

reference

Rete components, profiles and the graph→Ohm compiler.

  • spec: 09-graphs

☑ The spec editor#

reference

The hierarchical spec tree, references, AI actions, markdown.

  • spec: 10-specs

☑ The Context tab#

reference

Open tabs, page structure as data, set algebra over tabs, exports.

  • spec: 14-context

☑ Documents and annotations#

reference

PDF, Word, spreadsheet, slide, image and text viewers with anchored notes.

  • spec: 11-documents

☑ Storage, bundles and the mirror#

reference

Files first, bundles for portability, IndexedDB as a backup.

  • spec: 12-storage

☑ Apps and capabilities#

reference

Loading other people's code, and the capability list that decides what it can reach.

  • spec: 15-apps

☑ Packaging and installers#

reference

The build, the compiled help, the staged layout, the Windows wizard and the macOS DMG.

  • spec: 13-packaging

☑ Cross-cutting risks#

☐ Security gaps found in review#

risk urgent #security

Four findings deserve attention before anyone else's data is involved, each detailed in its own spec:

  1. The UI page has no navigation lock, so a top-level navigation would hand a remote origin the whole protocol surface.
  2. A script can point a profile that owns a stored API key at a different baseUrl and the key follows.
  3. The OpenAI host check is a substring match, so a lookalike domain receives the environment key.
  4. Served roots are not realpath-checked, so a symlink inside them escapes.
  • spec: 01-engine-and-shell
  • spec: 04-models-and-settings

☐ Correctness gaps found in review#

risk urgent #correctness

~= silently compiles to ==; the text-annotation occurrence index is computed by one rule and resolved by another; spreadsheet cell references can disagree with the workbook; an experiment with no evaluators reports a perfect score.

  • spec: 02-ohm-language
  • spec: 11-documents
  • spec: 06-experiments

☐ Streaming generation#

task high

Every provider is request/response today, so there is no token-by-token output and no way to cancel a generation. This is the main thing standing between the current console and a chat-shaped assistant.

  • spec: 04-models-and-settings

☐ Per-workspace sessions and the language picker#

task

The workspace concept is partly built: projects exist, but tabs all share one cookie jar and there is no per-workspace session partition or language selection yet.

  • spec: 01-engine-and-shell

☑ How to use these specs#

☑ They are generated, and they are data#

note

Each spec is authored as a JavaScript object under docs/specs/src and built into both <name>.spec.md (readable here) and <name>.spec.json (openable in Ohm's own spec editor). npm run specs rebuilds them; npm run specs -- --check fails when they are stale, and validates that every reference points at something real.

Status is meaningful: done describes code that exists, todo describes work that does not. The review findings are todo risk and task nodes, so the progress percentage on each spec is a rough measure of how much of it is actually built.