@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-201-aspects-and-anchors.md

@@ -0,0 +1,112 @@
+---
+id: N-para-201-aspects-and-anchors
+title: Aspects & Code Anchors
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - aspects-are-the
+  - anchor-formats-single
+  - applies-to-uses-glob
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Why Aspects Require Anchors
+
+Aspects (`~`) are unique among Paradigm's five symbols because they are the only ones that **require code anchors**. An anchor is a pointer to the exact lines of code where the aspect is enforced. This requirement exists for a practical reason: an aspect without an anchor is just a wish.
+
+Consider `~audit-required`. If you define it without anchors, you are saying "financial operations should be audited" — but there is no proof that they actually are. With anchors pointing to `src/middleware/audit.ts:15-35`, you are saying "financial operations are audited, and here is the enforcement code." AI agents can verify the anchor, developers can review it, and `paradigm_aspect_check` can validate that the code still exists.
+
+## Anchor Format
+
+Anchors support three formats:
+
+```yaml
+~rate-limited:
+  description: API endpoints are rate-limited to prevent abuse
+  anchors:
+    - src/middleware/rate-limiter.ts:42          # Single line
+    - src/middleware/rate-limiter.ts:42-78       # Line range
+    - src/decorators/throttle.ts:10,15,22       # Multiple specific lines
+  applies-to: ["#*-handler"]
+```
+
+- **Single line** (`file:42`) — Points to one specific line. Use when the enforcement is a single check or decorator.
+- **Range** (`file:42-78`) — Points to a block of code. Use when the enforcement spans multiple lines (a middleware function, a class method).
+- **Multiple lines** (`file:10,15,22`) — Points to several non-contiguous lines. Use when the enforcement is scattered across a file (multiple decorators, multiple conditional checks).
+
+Anchors must point to *real files with real code*. If the file does not exist or the lines are outside the file's range, `paradigm_aspect_check` will report an error.
+
+## The applies-to Pattern
+
+The `applies-to` field uses glob patterns to declare which symbols the aspect covers:
+
+```yaml
+~audit-required:
+  applies-to: ["#*Service"]         # All components ending in 'Service'
+
+~rate-limited:
+  applies-to: ["#*-handler", "#*-endpoint"]  # All handlers and endpoints
+
+~cached:
+  applies-to: ["#*-query"]          # All query components
+```
+
+This is declarative — it says "this aspect should apply to these components." AI agents use this to check whether a new component matching the pattern has the aspect applied. If you create `#billing-service` and `~audit-required` applies to `#*Service`, the agent knows to apply the audit aspect.
+
+## Defining Aspects in .purpose Files
+
+```yaml
+aspects:
+  ~audit-required:
+    description: All financial operations must log to the audit trail
+    anchors:
+      - src/middleware/audit.ts:15-35
+      - src/decorators/auditable.ts:1-20
+    applies-to: ["#*Service"]
+    enforcement: middleware
+    tags: [compliance, security]
+
+  ~rate-limited:
+    description: API endpoints enforce per-user rate limits
+    anchors:
+      - src/middleware/rate-limiter.ts:42-78
+    applies-to: ["#*-handler"]
+    enforcement: middleware
+    tags: [security, performance]
+```
+
+The `enforcement` field is optional metadata that describes *how* the aspect is enforced — via middleware, decorator, wrapper function, etc. It helps AI agents understand the enforcement mechanism when they need to apply the aspect to new components.
+
+## Validating Aspects
+
+Use `paradigm_aspect_check` to verify that an aspect's anchors are valid:
+
+```
+paradigm_aspect_check({ aspect: "~audit-required" })
+```
+
+This tool checks:
+1. **Anchor existence** — Do the referenced files exist?
+2. **Line validity** — Are the line numbers within the file's range?
+3. **Coverage** — Are all components matching `applies-to` actually covered?
+
+Run this after refactoring. If you move or rename files, the anchors break — and a broken anchor means the enforcement code is lost or relocated. The aspect check catches this drift.
+
+## Aspects vs Gates
+
+A common confusion: when should you use an aspect (`~`) versus a gate (`^`)? The distinction is clear:
+
+- **Gates** check a *specific condition at a specific time*. "Can this user access this project?" or "Is this feature flag enabled?" is a gate.
+- **Aspects** enforce rules *across many components as a pattern*. "All financial services must log to the audit trail" is an aspect.
+
+Gates are reactive (triggered per request or operation). Aspects are structural (enforced by code patterns). A gate checks one condition at one point; an aspect applies to all components matching a pattern.

package/dist/university-content/notes/N-para-201-component-patterns.md

@@ -0,0 +1,138 @@
+---
+id: N-para-201-component-patterns
+title: Component Patterns
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - feature-components-user-facing
+  - integration-components-third-party
+  - state-components-data
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## The Many Faces of `#`
+
+The `#` component is Paradigm's most used symbol — and intentionally the broadest. It covers everything from a React button to a database service to a CLI command parser. This breadth is a feature, not a bug: it means you never struggle to classify code. But it also means you need **tags** to create meaningful subcategories.
+
+This lesson covers the major component patterns and when to use each one.
+
+## Feature Components
+
+Feature components represent **user-facing functionality**. They are the things your users interact with — checkout, search, profile editing, notification preferences.
+
+```yaml
+#checkout:
+  description: Shopping cart checkout with payment processing
+  file: checkout.ts
+  tags: [feature, critical, payments]
+  flows: ["$checkout-flow"]
+  signals: ["!order-placed"]
+  gates: ["^authenticated"]
+
+#search:
+  description: Full-text search across products and content
+  file: search.ts
+  tags: [feature, search]
+```
+
+Feature components often have the richest cross-references: they participate in flows, emit signals, and require gates. They are the entry points into your system's behavior.
+
+## Integration Components
+
+Integration components wrap **third-party services**. They isolate external API calls behind a stable internal interface:
+
+```yaml
+#stripe-service:
+  description: Stripe API client for payment processing
+  file: stripe-service.ts
+  tags: [integration, stripe, payments]
+  signals: ["!payment-completed", "!payment-failed"]
+
+#sendgrid-client:
+  description: SendGrid email delivery wrapper
+  file: sendgrid.ts
+  tags: [integration, sendgrid, email]
+```
+
+The convention is to tag integrations with both `[integration]` and the service name (`[stripe]`, `[sendgrid]`). This lets you search for all integrations OR for all Stripe-related code specifically.
+
+## State Components
+
+State components manage **data storage and state containers** — databases, caches, in-memory stores, Redux slices:
+
+```yaml
+#user-store:
+  description: User data persistence and caching layer
+  file: user-store.ts
+  tags: [state, users, cache]
+
+#session-cache:
+  description: Redis-backed session storage with 24h TTL
+  file: session-cache.ts
+  tags: [state, session, redis]
+```
+
+State components are often referenced by many other components. Use `paradigm_ripple` before modifying them — a change to `#user-store` might impact every feature that reads user data.
+
+## Infrastructure Components
+
+Infrastructure components provide **foundational services** that other components depend on but users never directly interact with:
+
+```yaml
+#logger:
+  description: Structured logging with symbol tagging
+  file: logger.ts
+  tags: [infrastructure, observability]
+
+#config-loader:
+  description: Environment-aware configuration loading
+  file: config.ts
+  tags: [infrastructure, config]
+
+#database-pool:
+  description: PostgreSQL connection pool with health checks
+  file: db.ts
+  tags: [infrastructure, database, postgres]
+```
+
+Infrastructure components rarely have flows or gates, but they are often the most fragile — many other components depend on them. Check `paradigm_history_fragility` before making changes.
+
+## When to Split vs Combine
+
+A common question: should a large module be one component or several?
+
+**Split when:**
+- The module has distinct responsibilities that could change independently
+- Different parts require different gates or emit different signals
+- The file exceeds ~300 lines and contains clearly separable logic
+
+**Combine when:**
+- The parts are tightly coupled and always change together
+- Splitting would create components with trivial descriptions ("calls the other half")
+- The module is a cohesive unit with a single responsibility
+
+```yaml
+# Good split — distinct responsibilities
+#payment-processor:
+  description: Charges cards via Stripe
+#payment-validator:
+  description: Validates payment amounts and currencies
+
+# Bad split — artificial separation
+#payment-step-1:
+  description: First half of payment processing
+#payment-step-2:
+  description: Second half of payment processing
+```
+
+If you cannot describe the component without referencing the other half, they should be one component.

package/dist/university-content/notes/N-para-201-cross-cutting-concerns.md

@@ -0,0 +1,145 @@
+---
+id: N-para-201-cross-cutting-concerns
+title: Cross-Cutting Concerns
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - cross-cutting-concerns-apply
+  - common-aspects-audit
+  - applies-to-uses-glob
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Rules That Span the System
+
+Some requirements do not belong to any single component. "All financial operations must be audited." "All API endpoints must be rate-limited." "All sensitive data must be encrypted at rest." These are **cross-cutting concerns** — rules that apply across multiple components as a structural pattern rather than a per-request check.
+
+Paradigm models cross-cutting concerns as **aspects** (`~`). Unlike gates (which check access per request) or signals (which fire per event), aspects describe ongoing constraints that are enforced by code patterns, middleware, decorators, or architectural choices.
+
+## Common Aspect Patterns
+
+### Audit Trails
+
+```yaml
+~audit-required:
+  description: All financial operations must log to the audit trail with user, action, and timestamp
+  anchors:
+    - src/middleware/audit.ts:15-35
+    - src/decorators/auditable.ts:1-20
+  applies-to: ["#*Service"]
+  enforcement: middleware
+  tags: [compliance, security]
+```
+
+Audit aspects ensure that certain operations leave a trail. The anchors point to the middleware or decorator that performs the logging. Any service matching `#*Service` is expected to use this middleware.
+
+### Rate Limiting
+
+```yaml
+~rate-limited:
+  description: API endpoints enforce per-user rate limits (100 req/min default)
+  anchors:
+    - src/middleware/rate-limiter.ts:10-45
+  applies-to: ["#*-handler", "#*-endpoint"]
+  enforcement: middleware
+  tags: [security, performance]
+```
+
+Rate limiting protects against abuse. The aspect documents the default limit (100 req/min) and points to the middleware that enforces it.
+
+### Caching
+
+```yaml
+~cached:
+  description: Read-heavy queries use a 5-minute TTL cache
+  anchors:
+    - src/lib/cache-wrapper.ts:20-55
+  applies-to: ["#*-query"]
+  enforcement: wrapper-function
+  tags: [performance]
+```
+
+### Input Validation
+
+```yaml
+~validated:
+  description: All API inputs are validated against defined schemas before processing
+  anchors:
+    - src/middleware/validate.ts:1-30
+    - src/schemas/index.ts:1-50
+  applies-to: ["#*-handler"]
+  enforcement: middleware
+  tags: [security, data-integrity]
+```
+
+### Idempotency
+
+```yaml
+~idempotent:
+  description: Mutation endpoints use idempotency keys to prevent duplicate processing
+  anchors:
+    - src/middleware/idempotency.ts:15-60
+  applies-to: ["#*-handler"]
+  enforcement: middleware
+  tags: [reliability, payments]
+```
+
+### Encryption at Rest
+
+```yaml
+~encrypted-at-rest:
+  description: Sensitive fields are encrypted before storage using AES-256-GCM
+  anchors:
+    - src/lib/encryption.ts:10-45
+    - src/models/base-model.ts:30-50
+  applies-to: ["#*-store"]
+  enforcement: model-hook
+  tags: [security, compliance]
+```
+
+## The applies-to Glob Pattern
+
+The `applies-to` field uses glob patterns to declare which symbols the aspect covers:
+
+| Pattern | Matches |
+|---------|---------|
+| `#*Service` | `#payment-service`, `#email-service`, `#auth-service` |
+| `#*-handler` | `#login-handler`, `#webhook-handler` |
+| `#*-store` | `#user-store`, `#session-store` |
+| `#*` | All components (use sparingly) |
+
+When an AI agent creates a new component matching a pattern, it should check whether any aspects apply. If `~rate-limited` applies to `#*-handler` and the agent creates `#upload-handler`, the agent should ensure rate limiting middleware is applied.
+
+## Aspects vs Other Symbols
+
+Understanding when to use each symbol avoids misclassification:
+
+| If the rule... | Use |
+|----------------|-----|
+| Checks a specific condition per request or operation | `^` Gate |
+| Fires an event that triggers side effects | `!` Signal |
+| Applies the same pattern across many components | `~` Aspect |
+| Describes a multi-step process | `$` Flow |
+
+A rate limiter is an aspect (it applies the same pattern to all handlers), not a gate (it does not check authorization). An audit log is an aspect (it applies to all financial services), not a signal (it is a structural requirement, not a one-time event).
+
+## Maintaining Aspects During Refactors
+
+Aspects are the most maintenance-sensitive symbol because their anchors contain file paths and line numbers. When you refactor:
+
+1. Run `paradigm_aspect_check` before the refactor to know the current state.
+2. Make your code changes.
+3. Run `paradigm_aspect_check` again to find broken anchors.
+4. Update the anchors in the `.purpose` file to point to the new locations.
+
+This is a conscious trade-off: anchors create maintenance burden, but they prevent the much worse problem of unverified rules that silently stop being enforced.

package/dist/university-content/notes/N-para-201-disciplines.md

@@ -0,0 +1,187 @@
+---
+id: N-para-201-disciplines
+title: Disciplines
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - disciplines-define-how
+  - 14-disciplines-web
+  - auto-detection-at-init
+symbols: []
+difficulty: beginner
+estimatedMinutes: 7
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## How Symbols Map Across Domains
+
+A Paradigm `discipline` defines how directory patterns and code structures map to symbol types in a specific development domain. A web frontend project organizes code differently from a backend API, which differs from a CLI tool. Disciplines capture these differences so that tooling — the navigator, the logging conventions, gate recommendations, and auto-scan — works correctly regardless of your tech stack.
+
+## Auto-Detection
+
+When you run `paradigm shift` or `paradigm init`, Paradigm automatically detects the discipline from your project structure. It examines `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, and other project markers to infer the best match. The detected discipline is written to `.paradigm/config.yaml`:
+
+```yaml
+discipline: fullstack    # auto-detected from Next.js in package.json
+```
+
+Detection heuristics include: monorepo markers (workspaces), framework deps (Next.js → fullstack, React alone → web, Express alone → api), Python ML deps (PyTorch → ml), Rust crate deps (clap → cli, axum → api, bevy → game), and more. You can always override the detected value.
+
+## The 14 Disciplines
+
+Paradigm supports 14 disciplines, each with tailored symbol mappings, purpose-required paths, and scan patterns:
+
+| Discipline | When to Use | Key Directories |
+|------------|-------------|------------------|
+| `web` | Frontend-only (React, Vue, Svelte) | `components/`, `pages/`, `hooks/`, `stores/` |
+| `backend` | General backend (fallback) | `services/`, `routes/`, `models/` |
+| `fullstack` | SSR or combined frontend+backend (Next.js, Django) | `components/`, `pages/`, `api/`, `services/` |
+| `api` | API-only (Express, FastAPI, Gin) | `routes/`, `endpoints/`, `controllers/` |
+| `cli` | CLI tools (Node bin, Click, clap) | `commands/`, `cmd/` |
+| `ml` | Machine learning (PyTorch, TF, scikit-learn) | `models/`, `experiments/`, `pipelines/` |
+| `mobile` | Mobile apps (React Native, Flutter) | `screens/`, `widgets/`, `navigation/` |
+| `game` | Game dev (Bevy, Godot, Unity) | `gameplay/`, `entities/`, `systems/` |
+| `embedded` | Embedded/IoT (embedded-hal, PlatformIO) | `drivers/`, `hal/`, `protocols/` |
+| `devops` | Infrastructure (Terraform, Ansible) | `modules/`, `pipelines/`, `scripts/` |
+| `data` | Data engineering (dbt, Airflow, Spark) | `models/`, `dags/`, `transforms/` |
+| `library` | Reusable packages (npm, PyPI, crates) | `src/`, `lib/` |
+| `monorepo` | Multi-package repos (workspaces, Nx) | `packages/`, `apps/`, `libs/` |
+| `custom` | User-defined mappings | Whatever you configure |
+
+## Web Discipline
+
+In a web project, the primary units are routes, components, and pages:
+
+| Directory | Symbol | Rationale |
+|-----------|--------|-----------|
+| `routes/`, `pages/`, `views/` | `#` component | User-facing entry points |
+| `components/` | `#` component | Reusable UI elements |
+| `hooks/` | `#` component | Shared logic (hooks are code units, not signals) |
+| `stores/`, `state/` | `#` component (tag: `[state]`) | Client-side state |
+| `middleware/` | `^` gate | Route guards and auth checks |
+| `api/` | `#` component | API client wrappers |
+
+An important distinction: **hooks are components, not signals**. A frontend hook like `useAuth` encapsulates logic — it is `#useAuth`, a component. The `!` signal prefix is reserved for events that trigger decoupled side effects.
+
+## Backend / API Discipline
+
+In a backend or API project, the primary units are services, controllers, and models:
+
+| Directory | Symbol | Rationale |
+|-----------|--------|-----------|
+| `services/` | `#` component | Business logic |
+| `controllers/`, `handlers/` | `#` component | Request handlers |
+| `models/`, `entities/` | `#` component (tag: `[state]`) | Data models |
+| `middleware/`, `guards/` | `^` gate | Auth and validation |
+| `events/`, `listeners/` | `!` signal | Event emitters and handlers |
+| `jobs/`, `workers/` | `#` component | Background processing |
+| `integrations/`, `clients/` | `#` component (tag: `[integration]`) | External service wrappers |
+
+The `api` discipline is like `backend` but focused on HTTP endpoints (adds `endpoints/`, `controllers/`, `webhooks/`).
+
+## Fullstack Discipline
+
+The fullstack discipline combines both mappings. Paradigm determines which mapping to use based on the directory path:
+
+```
+src/
+  client/     → Web discipline mappings apply
+  server/     → Backend discipline mappings apply
+  shared/     → Common mappings (# for all code units)
+```
+
+Auto-detected for SSR frameworks like Next.js, Nuxt, SvelteKit, or when both React and Express are present.
+
+## Domain-Specific Disciplines
+
+**ML**: Scans `models/`, `experiments/`, `notebooks/`. Pipelines map to `$` flows. Training events map to `!` signals.
+
+**Data**: Scans `dbt/`, `dags/`, `transforms/`. ETL pipelines are `$` flows. Data quality checks are `!` signals.
+
+**Game**: Scans `gameplay/`, `entities/`, `systems/`. Game loops are `$` flows. Game events are `!` signals.
+
+**Embedded**: Scans `drivers/`, `hal/`, `protocols/`. State machines are `$` flows. Interrupts are `!` signals.
+
+## Why Disciplines Matter
+
+Disciplines affect four things:
+
+1. **Symbol mappings** — Each discipline populates the `logging.symbol-mapping` section in config.yaml with directory-to-symbol mappings appropriate for your domain.
+2. **Navigator generation** — `paradigm scan` uses the discipline to categorize directories and suggest symbol types for undocumented code.
+3. **Gate recommendations** — `paradigm_gates_for_route` uses the discipline to understand which routes exist and what patterns apply.
+4. **Auto-scan patterns** — `paradigm scan --auto` adds discipline-specific file patterns (e.g., ML scans `.ipynb` notebooks, game scans `.gd` scripts).
+
+With auto-detection, most projects get the right discipline without any manual configuration.
+
+## Custom Mappings
+
+If your project does not fit a standard discipline, you can override mappings in `config.yaml`:
+
+```yaml
+discipline: backend
+custom-mappings:
+  "workers/": "#"       # Override default if needed
+  "policies/": "^"      # Treat policies as gates
+  "sagas/": "$"         # Treat sagas as flows
+```
+
+Custom mappings extend (not replace) the discipline defaults. Or set `discipline: custom` and define everything yourself.
+
+## Stack Presets
+
+Disciplines tell Paradigm *what kind* of project you have (web, backend, mobile). Stack presets go one level deeper — they tell Paradigm *which framework* you are using. A stack preset layers framework-specific configuration on top of the discipline.
+
+Paradigm ships 16 stack presets:
+
+| Preset | Discipline | What It Adds |
+|--------|------------|-------------|
+| `nextjs` | fullstack | `app/` routes, server actions, RSC patterns |
+| `remix` | fullstack | loader/action patterns, nested routes |
+| `sveltekit` | fullstack | `+page.svelte`, `+server.ts` patterns |
+| `nuxt` | fullstack | `composables/`, auto-imports |
+| `react-spa` | web | CRA/Vite SPA patterns, `hooks/`, `contexts/` |
+| `vue-spa` | web | Composition API, Pinia stores |
+| `express` | api | `app.get/post`, middleware chains |
+| `fastapi` | api | `@app.get`, Pydantic models, dependency injection |
+| `django` | fullstack | `views.py`, `models.py`, `urls.py` |
+| `flask` | api | `@app.route`, blueprints |
+| `gin-go` | api | `r.GET`, handler groups |
+| `axum-rs` | api | Axum extractors, tower middleware |
+| `swift-ios` | mobile | SwiftUI views, `@Observable`, navigation |
+| `kotlin-android` | mobile | Jetpack Compose, ViewModels, Hilt |
+| `react-native` | mobile | Expo/bare RN, navigation, native modules |
+| `flutter` | mobile | Widgets, BLoC/Riverpod, platform channels |
+
+Stack presets are auto-detected during `paradigm init` from your dependencies and project files. You can also specify one explicitly:
+
+```bash
+paradigm init --stack nextjs
+```
+
+The detected stack is written to config.yaml:
+
+```yaml
+discipline: fullstack
+stack: nextjs
+```
+
+Stack presets add three things on top of the discipline:
+1. **Refined symbol mappings** — Framework-specific directories (e.g., `app/api/` for Next.js route handlers)
+2. **Purpose-required paths** — Directories that should have `.purpose` files for the framework to work well with Paradigm
+3. **Scan hints** — Framework-specific patterns for component detection, route patterns, auth patterns, and state management
+
+To see all available presets:
+
+```bash
+paradigm presets
+paradigm presets --discipline mobile   # Filter by discipline
+```
+
+Stack presets solve the cold-start problem: when you run `paradigm init` on an existing Next.js project, the preset knows to look for `app/` routes, server components, and API handlers — producing meaningful `.purpose` scaffolding instead of generic stubs.