@a-company/paradigm 5.37.11 → 6.0.2

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

@@ -0,0 +1,175 @@
+---
+id: N-para-201-architecture-review
+title: Putting It All Together
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - feature-building-follows
+  - implementation-comes-last
+  - check-existing-aspects
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Building a Complete Feature
+
+You have learned flows, gates, aspects, disciplines, naming conventions, component patterns, signal patterns, and cross-cutting concerns. Now let us walk through building a complete feature from scratch, using every tool in the Paradigm toolkit. The feature: **a team invitation system** where team admins can invite new members via email.
+
+## Step 1: Identify Components
+
+Start by listing the code units you will need:
+
+```yaml
+#invitation-service:
+  description: Creates and manages team invitations
+  tags: [feature, teams]
+
+#invitation-email:
+  description: Sends invitation emails via SendGrid
+  tags: [integration, sendgrid, email]
+
+#invitation-token:
+  description: Generates and validates secure invitation tokens
+  tags: [infrastructure, security]
+
+#invitation-store:
+  description: Persists invitations with status tracking
+  tags: [state, teams]
+```
+
+Four components — one feature, one integration, one infrastructure, one state. Each has a clear responsibility and appropriate tags.
+
+## Step 2: Define the Flow
+
+The invitation process spans all four components in sequence:
+
+```yaml
+$team-invitation-flow:
+  description: Admin invites a user, email is sent, user accepts and joins team
+  steps:
+    - component: "#invitation-service"
+      action: create-invitation
+      description: Validates admin permissions and creates invitation record
+    - component: "#invitation-token"
+      action: generate-token
+      description: Creates a cryptographically secure token with 7-day expiry
+    - component: "#invitation-store"
+      action: persist-invitation
+      description: Saves invitation with pending status
+    - component: "#invitation-email"
+      action: send-invite
+      description: Sends email with accept link containing the token
+  signals: ["!invitation-sent", "!invitation-accepted"]
+  gates: ["^authenticated", "^team-admin"]
+```
+
+## Step 3: Add Gates
+
+Two gates are needed. First, check `portal.yaml` for existing gates. `^authenticated` likely exists. `^team-admin` may need to be created:
+
+```yaml
+# In portal.yaml
+gates:
+  ^team-admin:
+    description: User must be an admin of the specified team
+    check: team.admins.includes(req.user.id)
+    type: role
+    requires: [^authenticated]
+    effects: []
+
+routes:
+  "POST /api/teams/:id/invitations": [^authenticated, ^team-admin]
+  "POST /api/invitations/:token/accept": [^authenticated]
+  "GET /api/teams/:id/invitations": [^authenticated, ^team-admin]
+  "DELETE /api/invitations/:id": [^authenticated, ^team-admin]
+```
+
+Notice that accepting an invitation only requires `^authenticated` — any logged-in user with a valid token can accept. But creating, listing, and deleting invitations requires `^team-admin`.
+
+## Step 4: Define Signals
+
+```yaml
+!invitation-sent:
+  description: An invitation email was successfully sent to a prospective team member
+  emitters: ["#invitation-service"]
+  category: business
+  data:
+    invitationId: string
+    teamId: string
+    email: string
+
+!invitation-accepted:
+  description: A user accepted a team invitation and joined the team
+  emitters: ["#invitation-service"]
+  category: business
+  data:
+    invitationId: string
+    teamId: string
+    userId: string
+```
+
+These business signals enable decoupled side effects — an analytics tracker can listen for `!invitation-accepted` to track conversion rates, and a notification service can alert existing team members.
+
+## Step 5: Apply Aspects
+
+Check which aspects apply to the new components:
+
+- `~audit-required` applies to `#*Service` → `#invitation-service` is covered. Ensure the audit middleware is applied.
+- `~rate-limited` applies to `#*-handler` → Not directly applicable here (no handler component), but the API route should go through the rate limiter.
+- `~validated` applies to `#*-handler` → The invitation endpoint should validate input (email format, team existence).
+
+## Step 6: Write the .purpose File
+
+Assemble everything into `src/invitations/.purpose`:
+
+```yaml
+name: Team Invitations
+description: Team admin invitation system with email delivery and token-based acceptance
+context:
+  - Invitation tokens expire after 7 days
+  - Maximum 50 pending invitations per team
+  - Uses SendGrid for email delivery
+
+components:
+  #invitation-service:
+    description: Creates and manages team invitations
+    file: invitation-service.ts
+    tags: [feature, teams]
+    flows: ["$team-invitation-flow"]
+    signals: ["!invitation-sent", "!invitation-accepted"]
+    gates: ["^authenticated", "^team-admin"]
+    aspects: ["~audit-required"]
+  # ... (remaining components)
+
+flows:
+  $team-invitation-flow:
+    # ... (as defined above)
+
+signals:
+  !invitation-sent:
+    # ... (as defined above)
+  !invitation-accepted:
+    # ... (as defined above)
+```
+
+## Step 7: Validate
+
+Before writing any implementation code, validate the Paradigm definitions:
+
+1. `paradigm_purpose_validate` — Checks the .purpose file for schema errors.
+2. `paradigm_flow_check` — Verifies the flow references valid components.
+3. `paradigm_aspect_check` — Confirms aspect anchors are valid for applied aspects.
+4. `paradigm_ripple` — Shows what existing code is affected by the new components.
+
+## The Pattern
+
+Every feature follows this pattern: **identify components** → **define flows** → **add gates** → **define signals** → **apply aspects** → **write .purpose** → **validate** → **implement**. The implementation comes last — after the architecture is documented and validated. This front-loaded documentation pays dividends: AI agents can navigate the new feature immediately, security is defined before code, and the team has a clear map of what will be built.

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

@@ -0,0 +1,79 @@
+---
+id: N-para-201-aspect-graph
+title: The Aspect Graph
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - aspect-graph-connects
+  - five-aspect-categories
+  - five-edge-relations
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## What Is the Aspect Graph?
+
+In earlier lessons you learned that aspects (`~`) represent cross-cutting rules, constraints, and configuration values anchored to specific lines of code. The **aspect graph** connects those aspects to each other and to the rest of your symbol system — components, gates, flows, and signals — creating a queryable relationship map.
+
+Think of it this way: a single aspect like `~token-expiry-24h` is useful on its own. But when you can see that it is *enforced by* `^authenticated`, *related to* `~refresh-token-7d`, and linked to a lore entry explaining why the team chose 24 hours — that is the graph at work.
+
+## v3.5 Aspect Fields
+
+Paradigm v3.5 extended aspects with structured fields that make them graph-ready:
+
+```yaml
+aspects:
+  ~rate-limit-100:
+    description: API rate limited to 100 requests per minute
+    value: 100/min
+    category: constraint
+    severity: high
+    anchors:
+      - src/middleware/rate-limiter.ts:12-18
+    applies-to: [#api-gateway]
+    edges:
+      - symbol: ^authenticated
+        relation: enforced-by
+    tags: [security, performance]
+```
+
+Key fields:
+- **value** — The concrete value (a number, duration, threshold) making aspects searchable by content
+- **category** — One of five types: `rule` (behavioral), `decision` (architectural choice), `constraint` (hard limit), `configuration` (environment-specific), `invariant` (always-true condition)
+- **severity** — Impact of violation: `low`, `medium`, `high`, `critical`
+- **edges** — Explicit relationships to other symbols with typed relations: `enforced-by`, `depends-on`, `contradicts`, `supersedes`, `related-to`
+- **lore** — References to lore entries providing historical context
+
+## Working with the Graph
+
+Seven MCP tools let you interact with the aspect graph:
+
+| Tool | Purpose |
+|------|---------|
+| `paradigm_aspect_search` | Find aspects by keyword — uses a three-tier search (learned mappings, full-text, fuzzy) |
+| `paradigm_aspect_get` | Deep-dive: full definition, code snippets at anchors, edges, linked lore |
+| `paradigm_aspect_graph` | Explore the neighborhood around a symbol (N hops out) |
+| `paradigm_aspect_heatmap` | See which aspects are accessed most (search, ripple, navigate, direct) |
+| `paradigm_aspect_suggest_scan` | Scan a source file for undocumented aspects (magic numbers, hardcoded strings, rate limits, etc.) |
+| `paradigm_aspect_drift` | Check if code at anchored lines changed since last scan (SHA-256 hash comparison) |
+| `paradigm_aspect_confirm` | Confirm a search result to improve future search accuracy (learning loop) |
+
+The graph is stored as a SQLite database at `.paradigm/aspect-graph.db` — a derived artifact rebuilt by `paradigm_reindex`. The YAML `.purpose` files remain the source of truth.
+
+## When to Use the Aspect Graph
+
+- **Before modifying enforcement code** — call `paradigm_aspect_drift` to check for stale anchors
+- **Exploring unfamiliar rules** — call `paradigm_aspect_search` then `paradigm_aspect_get` for full context
+- **Understanding impact** — call `paradigm_aspect_graph` to see what a change affects
+- **Finding undocumented rules** — call `paradigm_aspect_suggest_scan` on source files
+
+> **Deep dive:** PARA 501 covers the SQLite schema, three-tier search internals, the learning loop, edge origins (explicit vs inferred vs learned), and the materialization pipeline in detail.

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.