arch: cleanup / doc

arnog · arnog · commit 8b22e229f908 · 2026-02-10T11:48:38.000-08:00
diff --git a/docs/PLAYGROUND.md b/docs/PLAYGROUND.md
@@ -1,5 +1,9 @@
 # Playground Test Results
 
+> This file is a snapshot report for `test/playground.ts`, not a complete API
+> reference. For current user-facing API usage, see [`docs/README.md`](./README.md)
+> and the repository [`README.md`](../README.md).
+
 This document summarizes the status of various test snippets from
 `test/playground.ts`.
 
@@ -115,7 +119,8 @@ This document summarizes the status of various test snippets from
 **Note:** `.replace({match: 'a', replace: 2})` on `a*x + b` returns `2` instead
 of `2*x + b`. The bug is in `parseRulePart` (rules.ts:350) which auto-converts
 all single-character symbols to wildcards. So `'a'` becomes `'_a'`, matching ANY
-expression rather than the literal symbol `a`. See TODO.md #23.
+expression rather than the literal symbol `a`. This behavior is tracked in the
+internal backlog.
 
 ### Expected Behavior (Not Bugs)
 
@@ -154,8 +159,8 @@ expression rather than the literal symbol `a`. See TODO.md #23.
 
 **Note:** `isEqual` is for mathematical equality (vs `isSame` for structural
 equality). For equations, `isEqual` should check if `(LHS1-RHS1)/(LHS2-RHS2)`
-simplifies to a non-zero constant, indicating the same solution set. See TODO.md
-#22.
+simplifies to a non-zero constant, indicating the same solution set. This
+behavior is tracked in the internal backlog.
 
 ---
 
diff --git a/docs/SIMPLIFICATIONS.md b/docs/SIMPLIFICATIONS.md
@@ -1,7 +1,14 @@
 # Simplification Issues Report
 
-This document catalogs simplification behaviors that need attention, organized
-by priority and category.
+> This document is a categorized simplification report and not a full API
+> reference. For current user-facing API documentation, see
+> [`docs/README.md`](./README.md) and [`README.md`](../README.md).
+
+Checked: 2026-02-01 Compute Engine version (package.json): 0.33.0
+
+This document catalogs historical and current simplification behaviors,
+including resolved items and remaining limitations, organized by priority and
+category.
 
 ## Summary
 
diff --git a/docs/SIMPLIFY.md b/docs/SIMPLIFY.md
@@ -1,4 +1,8 @@
-# Simplification status for issue #178
+# Simplification Snapshot (Issue #178)
+
+> This file tracks issue-specific simplification snapshots and is not the
+> canonical API guide. For current API usage and workflow helper options, see
+> [`docs/README.md`](./README.md) and [`README.md`](../README.md).
 
 Source: cortex-js/compute-engine#178 ("x+x does not simplify to 2x")
 
diff --git a/docs/architecture/CURRENT-ARCHITECTURE.md b/docs/architecture/CURRENT-ARCHITECTURE.md
@@ -11,37 +11,95 @@ This document captures the implemented architecture after the recent modularizat
 
 ## Layering Model
 
-1. Kernel type layer
+```
+┌─────────────────────────────────────────────────┐
+│  4. Composition root                            │
+│     index.ts (ComputeEngine)                    │
+│     Composes services, exposes public API        │
+├─────────────────────────────────────────────────┤
+│  3. Runtime services                            │
+│     engine-*.ts                                 │
+│     One bounded concern per file                │
+├─────────────────────────────────────────────────┤
+│  2. Specialized type wrappers                   │
+│     types-*.ts, global-types.ts                 │
+│     Bind kernel generics to concrete types      │
+├─────────────────────────────────────────────────┤
+│  1. Kernel type layer                           │
+│     types-kernel-*.ts                           │
+│     Generic type contracts (no engine imports)  │
+└─────────────────────────────────────────────────┘
+```
+
+### 1. Kernel type layer
 - Files: `types-kernel-*.ts`
 - Responsibility: generic type contracts for evaluation/serialization behavior without engine-specific concrete types.
 - Rule: no dependency on `ComputeEngine` implementation modules.
 
-2. Specialized type wrappers
+### 2. Specialized type wrappers
 - Files: `types-*.ts`, `global-types.ts`
 - Responsibility: bind kernel generics to concrete compute-engine types (`BoxedExpression`, `IComputeEngine`, etc.).
 - Rule: avoid importing runtime implementation modules.
 
-3. Runtime services
+### 3. Runtime services
 - Files: `engine-*.ts`
 - Responsibility: focused implementation concerns (parse entrypoints, startup/bootstrap, configuration lifecycle, numeric config, scope/assumptions/sequences, workflow helpers, validation helpers, extension contracts).
 - Rule: services should not become secondary monoliths; each service owns one bounded concern.
 
-4. Composition root
+### 4. Composition root
 - File: `index.ts` (`ComputeEngine`)
 - Responsibility: compose services, expose public API methods, and own lifecycle orchestration.
 - Rule: business logic should prefer service modules; `ComputeEngine` should remain an API shell and integration point.
 
-## Service Boundaries (Implemented)
-
-- Startup/bootstrap: `engine-startup-coordinator.ts`, `engine-library-bootstrap.ts`
-- Parse defaults/policy: `engine-parse-entrypoint.ts`
-- Workflow API helpers: `engine-workflow-entrypoints.ts`
-- Validation/error expression entrypoints: `engine-validation-entrypoints.ts`
-- Numeric policy/state: `engine-numeric-configuration.ts`
-- Runtime limits/verification state: `engine-runtime-state.ts`
-- Configuration lifecycle/reset fan-out: `engine-configuration-lifecycle.ts`
-- Compilation target registry: `engine-compilation-targets.ts`
-- Extension contracts: `engine-extension-contracts.ts`
+## Service Inventory
+
+### Startup & Initialization
+| File | Responsibility |
+|------|---------------|
+| `engine-startup-coordinator.ts` | Orchestrates initialization sequence: common numbers, library bootstrap, common symbols |
+| `engine-library-bootstrap.ts` | Resolves library entries, topological sort, loads definitions, collects LaTeX dictionaries |
+| `engine-common-symbols.ts` | Initializes well-known symbol bindings (True, False, Pi, E, Nothing) |
+
+### Parsing & Workflows
+| File | Responsibility |
+|------|---------------|
+| `engine-parse-entrypoint.ts` | Engine-specific parse defaults, symbol type resolution, boxing of parse results |
+| `engine-workflow-entrypoints.ts` | High-level `parseSimplify/parseEvaluate/parseNumeric` combining parse + operation |
+
+### Validation & Errors
+| File | Responsibility |
+|------|---------------|
+| `engine-validation-entrypoints.ts` | Factory functions for error and type-mismatch expressions |
+| `engine-extension-contracts.ts` | Runtime contract validation for compilation targets, libraries, and compile options |
+
+### Engine State
+| File | Responsibility |
+|------|---------------|
+| `engine-numeric-configuration.ts` | Precision, tolerance, angular unit, and Decimal.js configuration |
+| `engine-runtime-state.ts` | Execution limits (time, iteration, recursion) and verification state |
+| `engine-configuration-lifecycle.ts` | Configuration change propagation and reset fan-out |
+| `engine-cache.ts` | Expression and rule-set caching with generation-based invalidation |
+| `engine-latex-dictionary-state.ts` | LaTeX dictionary indexing and rebuild |
+
+### Scoping & Declarations
+| File | Responsibility |
+|------|---------------|
+| `engine-scope.ts` | Lexical scope push/pop, eval context management, symbol lookup |
+| `engine-declarations.ts` | Symbol and operator declaration, type declaration, assignment |
+| `engine-assumptions.ts` | Assumption management, `ask()`, `verify()`, `forget()` |
+| `engine-sequences.ts` | Sequence declaration, OEIS lookup, recurrence evaluation |
+
+### Expression Construction
+| File | Responsibility |
+|------|---------------|
+| `engine-expression-entrypoints.ts` | Symbol and number expression creation with definition binding |
+| `engine-simplification-rules.ts` | Built-in simplification rule initialization |
+
+### Compilation
+| File | Responsibility |
+|------|---------------|
+| `engine-compilation-targets.ts` | Registry for named compilation targets (JavaScript, GLSL, etc.) |
+| `engine-type-resolver.ts` | Type resolution callback for parser integration |
 
 ## Public Workflow API Policy
 
@@ -55,10 +113,13 @@ This document captures the implemented architecture after the recent modularizat
   - Parse presets: `parseMode = strict | permissive`
 
 Precedence rule across workflow helpers:
-- Explicit low-level options win over presets.
+- Explicit low-level options always win over presets.
   - `parse.strict` overrides `parseMode`
   - `evaluate.numericApproximation` overrides `evaluateMode`
   - `simplify.strategy` overrides `simplifyMode`
+- This is implemented via object spread: the preset sets a default, then `...options.parse` overwrites it.
+
+Note: `simplifyMode: 'trigonometric'` maps to the internal `strategy: 'fu'` (the Fu algorithm for trigonometric simplification, named after Fu, Zhong, and Zeng).
 
 ## Extension Contracts (Runtime Guards)
 
@@ -92,12 +153,14 @@ Rules:
 
 ## Guardrails
 
-- Circular dependency budget: `0` (checked in `typecheck` + `check:deps` workflows).
+- **Circular dependency budget: `0`** — no cycles of any kind (runtime or type-only). Checked via `npx madge --circular --extensions ts src/compute-engine`.
+- ESLint `import/no-restricted-paths` enforces layered dependencies (35 zone rules in `.eslintrc.cjs`). Run with `npm run check:deps`.
 - Public type surfaces must not include explicit `any`.
 - Contract tests exist for extension seams (`test/compute-engine/extension-contracts.test.ts`).
 
 ## Immediate Next Work
 
-1. Keep shrinking `ComputeEngine` orchestration by extracting remaining utility glue.
+1. Add tests for library circular dependency detection and compilation target unregistration/re-registration.
 2. Expand extension contract tests to additional compile-target families and compile-edge payloads.
-3. Keep documentation synchronized between kernel contracts and specialized wrappers.
+3. Consider skipping contract validation for built-in compilation targets to reduce startup cost.
+4. Keep documentation synchronized between kernel contracts and specialized wrappers.
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -0,0 +1,14 @@
+# Architecture Docs
+
+This directory contains internal architecture notes and refactor plans.
+
+These documents are intended for maintainers and contributors. They describe
+module boundaries, dependency direction, and implementation planning, and are
+not a stable public API reference.
+
+Recommended starting points:
+
+- [`CURRENT-ARCHITECTURE.md`](./CURRENT-ARCHITECTURE.md) for the current module
+  map and extension boundaries.
+- [`ZERO-CYCLES-PLAN.md`](./ZERO-CYCLES-PLAN.md) for cycle-elimination status.
+- [`PLAN.md`](./PLAN.md) for the consolidated roadmap.
diff --git a/src/compute-engine/engine-library-bootstrap.ts b/src/compute-engine/engine-library-bootstrap.ts
@@ -67,11 +67,5 @@ export function getLatexDictionaryForDomain(
       ? STANDARD_LIBRARIES
       : STANDARD_LIBRARIES.filter((entry) => entry.name === domain);
 
-  const result: LatexDictionaryEntry[] = [];
-  for (const library of libraries) {
-    if (library.latexDictionary)
-      result.push(...(library.latexDictionary as LatexDictionaryEntry[]));
-  }
-
-  return result;
+  return collectLibraryLatexEntries(libraries);
 }
diff --git a/src/compute-engine/engine-workflow-entrypoints.ts b/src/compute-engine/engine-workflow-entrypoints.ts
@@ -1,6 +1,15 @@
 import type { BoxedExpression } from './global-types';
 import type { LatexString } from './latex-syntax/types';
 import type { ParseEntrypointOptions } from './engine-parse-entrypoint';
+import type {
+  WorkflowParseMode,
+  WorkflowEvaluateMode,
+  WorkflowSimplifyMode,
+  WorkflowParseOptions,
+  WorkflowSimplifyOptions,
+  WorkflowEvaluateOptions,
+  WorkflowNumericOptions,
+} from './types-engine';
 
 type WorkflowHost = {
   parse(
@@ -9,34 +18,13 @@ type WorkflowHost = {
   ): BoxedExpression | null;
 };
 
-export type ParseMode = 'strict' | 'permissive';
-export type EvaluateMode = 'exact' | 'numeric';
-export type SimplifyMode = 'default' | 'trigonometric';
-
-type WorkflowParseOptions = {
-  parseMode?: ParseMode;
-  parse?: ParseEntrypointOptions;
-};
-
-export type ParseSimplifyOptions = {
-  parseMode?: ParseMode;
-  simplifyMode?: SimplifyMode;
-  parse?: ParseEntrypointOptions;
-  simplify?: Parameters<BoxedExpression['simplify']>[0];
-};
-
-export type ParseEvaluateOptions = {
-  parseMode?: ParseMode;
-  evaluateMode?: EvaluateMode;
-  parse?: ParseEntrypointOptions;
-  evaluate?: Parameters<BoxedExpression['evaluate']>[0];
-};
-
-export type ParseNumericOptions = {
-  parseMode?: ParseMode;
-  parse?: ParseEntrypointOptions;
-};
-
+/**
+ * Translate workflow parse-mode preset into low-level parse options.
+ *
+ * **Precedence rule:** explicit `parse.strict` overrides `parseMode`.
+ * For example `{ parseMode: 'permissive', parse: { strict: true } }` results
+ * in `{ strict: true }` because object-spread puts `parse.*` last.
+ */
 function getParseOptions(
   options?: WorkflowParseOptions
 ): ParseEntrypointOptions | undefined {
@@ -46,17 +34,32 @@ function getParseOptions(
   return { strict, ...options.parse };
 }
 
+/**
+ * Translate workflow evaluate-mode preset into low-level evaluate options.
+ *
+ * **Precedence rule:** explicit `evaluate.numericApproximation` overrides
+ * `evaluateMode`.
+ */
 function getEvaluateOptions(
-  options?: ParseEvaluateOptions
+  options?: WorkflowEvaluateOptions
 ): Parameters<BoxedExpression['evaluate']>[0] | undefined {
   if (options?.evaluateMode === undefined) return options?.evaluate;
 
   const numericApproximation = options.evaluateMode === 'numeric';
   return { numericApproximation, ...options.evaluate };
 }
 
+/**
+ * Translate workflow simplify-mode preset into low-level simplify options.
+ *
+ * **Precedence rule:** explicit `simplify.strategy` overrides `simplifyMode`.
+ *
+ * The `'trigonometric'` mode maps to the `'fu'` strategy, which is the
+ * Fu algorithm for trigonometric simplification (named after the paper by
+ * Fu, Zhong, and Zeng).
+ */
 function getSimplifyOptions(
-  options?: ParseSimplifyOptions
+  options?: WorkflowSimplifyOptions
 ): Parameters<BoxedExpression['simplify']>[0] | undefined {
   if (options?.simplifyMode === undefined) return options?.simplify;
 
@@ -67,7 +70,7 @@ function getSimplifyOptions(
 export function parseAndSimplify(
   engine: WorkflowHost,
   latex: LatexString | null,
-  options?: ParseSimplifyOptions
+  options?: WorkflowSimplifyOptions
 ): BoxedExpression | null {
   const parsed = engine.parse(latex, getParseOptions(options));
   if (parsed === null) return null;
@@ -77,7 +80,7 @@ export function parseAndSimplify(
 export function parseAndEvaluate(
   engine: WorkflowHost,
   latex: LatexString | null,
-  options?: ParseEvaluateOptions
+  options?: WorkflowEvaluateOptions
 ): BoxedExpression | null {
   const parsed = engine.parse(latex, getParseOptions(options));
   if (parsed === null) return null;
@@ -87,7 +90,7 @@ export function parseAndEvaluate(
 export function parseAndNumeric(
   engine: WorkflowHost,
   latex: LatexString | null,
-  options?: ParseNumericOptions
+  options?: WorkflowNumericOptions
 ): BoxedExpression | null {
   const parsed = engine.parse(latex, getParseOptions(options));
   if (parsed === null) return null;
diff --git a/src/compute-engine/index.ts b/src/compute-engine/index.ts
