@a-company/paradigm 5.38.0 → 6.0.2

package/dist/university-content/notes/N-para-201-flows-deep-dive.md

@@ -0,0 +1,119 @@
+---
+id: N-para-201-flows-deep-dive
+title: Flows in Depth
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - create-flows-when
+  - steps-are-component
+  - define-flows-in
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## When to Create a Flow
+
+Not every process needs a `$flow`. The rule of thumb is: **create a flow when logic spans three or more components in a specific order**. A two-component interaction (service A calls service B) is simple enough to document in the component's `.purpose` entry. But once a third component enters the picture — and the order matters — a flow captures the choreography that no single component can describe.
+
+Consider these scenarios:
+- User clicks "Buy" → cart validates → payment charges → order creates → email sends. That is four components in sequence. This needs a `$checkout-flow`.
+- A cron job triggers → data fetches → report generates → file uploads → Slack notifies. Five components. This needs a `$daily-report-flow`.
+- A controller calls a service which returns data. Two components, no sequence ambiguity. This does NOT need a flow.
+
+## Flow Step Structure
+
+Each step in a flow is a `component + action` pair. The component references a `#component` defined in a `.purpose` file, and the action describes what that component does in this step:
+
+```yaml
+flows:
+  $onboarding:
+    description: New user setup from registration to first project
+    steps:
+      - component: "#auth-handler"
+        action: create-account
+        description: Validates email, hashes password, creates user record
+      - component: "#email-service"
+        action: send-welcome
+        description: Sends welcome email with verification link
+      - component: "#project-service"
+        action: create-default-project
+        description: Creates a starter project for the new user
+      - component: "#notification-service"
+        action: notify-team
+        description: Alerts the team Slack channel about the new signup
+    signals: ["!user-created", "!welcome-email-sent"]
+    gates: []
+```
+
+The `description` on each step is optional but valuable — it tells AI agents what happens at each point without reading the source code.
+
+## Documenting Flows in .purpose Files
+
+Flows are defined in the `flows` section of a `.purpose` file, usually in the directory of the *initiating* component. If the checkout flow starts in the cart module, define `$checkout-flow` in `src/cart/.purpose`. The flow references components from other directories — that is expected and correct.
+
+You can also reference flows from component definitions:
+
+```yaml
+components:
+  #cart-service:
+    description: Shopping cart management
+    flows: ["$checkout-flow", "$cart-abandonment-flow"]
+```
+
+This bidirectional referencing lets `paradigm_ripple` calculate the full impact when you modify a component — it knows which flows pass through it.
+
+## Flow Validation
+
+Paradigm provides `paradigm_flow_check` to check that your flow definitions are consistent:
+
+```
+paradigm_flow_check({ flowId: "$checkout-flow", checkImplementation: true })
+```
+
+With `checkImplementation: true`, the validator goes beyond schema checks — it verifies that the referenced components exist in `.purpose` files, that the actions are implemented in the codebase, and that any signals listed are actually emitted. This catches drift between documentation and code.
+
+You can also validate all flows at once by omitting the `flowId` parameter. This is useful as a pre-commit check or CI step.
+
+## Circular Dependency Detection
+
+When flows reference each other via `relatedFlows` or step-level `$flow` symbols, they form a dependency graph. Paradigm automatically detects circular dependencies in this graph using depth-first search.
+
+A circular dependency looks like this:
+
+```yaml
+$checkout-flow:
+  relatedFlows: [$payment-flow]
+$payment-flow:
+  relatedFlows: [$checkout-flow]  # Creates a cycle!
+```
+
+When you run `paradigm_flow_check({})` (validate all flows), the output includes a `circularDependencies` section:
+
+```
+⚠ Circular Dependencies (1)
+
+  $checkout-flow → $payment-flow → $checkout-flow
+
+  Resolution: Break the cycle by extracting shared logic into a
+  separate flow, or remove one direction of the dependency.
+```
+
+To resolve circular dependencies:
+1. **Extract shared logic** into a new flow that both original flows reference
+2. **Remove one direction** if only one flow truly depends on the other
+3. **Replace with signals** — use `!signal` communication instead of direct flow references
+
+Circular dependencies are not just a documentation problem — they indicate architectural coupling that can lead to cascading failures and maintenance difficulty.
+
+## Flows Are Documentation, Not Orchestration
+
+A critical distinction: flows describe *what happens*, not *how to make it happen*. They are not workflow engines or saga orchestrators. Your code still calls services, handles errors, and manages state however it needs to. The flow definition is metadata that helps humans and AI agents understand the sequence — it does not replace your implementation.

package/dist/university-content/notes/N-para-201-gates-deep-dive.md

@@ -0,0 +1,165 @@
+---
+id: N-para-201-gates-deep-dive
+title: Gates in Depth
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - gate-types-include
+  - check-expressions-are
+  - gates-chain-via
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Gate Types
+
+Gates are general-purpose condition checkers. While authorization is a common use case, gates can check any defined condition — feature flags, environment requirements, data prerequisites, system health, and more. Here are the common gate types:
+
+**Auth gates** verify identity — is the user who they claim to be?
+```yaml
+^authenticated:
+  description: User must have a valid session
+  check: req.session.userId != null
+  type: auth
+```
+
+**Role gates** verify permission level — does the user hold the right role?
+```yaml
+^project-admin:
+  description: User must be an admin of the project
+  check: project.admins.includes(req.user.id)
+  type: role
+  requires: [^authenticated]
+```
+
+**Ownership gates** verify resource ownership — does the user own this specific item?
+```yaml
+^comment-author:
+  description: User must be the author of this comment
+  check: comment.authorId === req.user.id
+  type: ownership
+  requires: [^authenticated]
+```
+
+**State-precondition gates** verify system state — is the system in the right condition?
+```yaml
+^payment-method-exists:
+  description: User must have a payment method on file
+  check: user.paymentMethods.length > 0
+  type: state-precondition
+  requires: [^authenticated]
+```
+
+**Environment gates** verify deployment context — is the system running in the right environment?
+```yaml
+^production-only:
+  description: Action is restricted to production environment
+  check: process.env.NODE_ENV === 'production'
+  type: environment
+```
+
+**Capability gates** verify that a feature or capability is available:
+```yaml
+^feature-enabled:
+  description: The feature flag must be active for this user
+  check: features.isEnabled('new-checkout', req.user)
+  type: capability
+```
+
+**Data-readiness gates** verify that required data exists before proceeding:
+```yaml
+^profile-complete:
+  description: User must have completed their profile before accessing this feature
+  check: user.profile.isComplete === true
+  type: data-readiness
+```
+
+The `type` field is metadata for humans and tools — Paradigm does not enforce different behavior based on type. But categorizing gates helps AI agents suggest appropriate checks. Auth, role, and ownership are common in web applications, while state-precondition, environment, capability, and data-readiness gates are equally important across all disciplines.
+
+## Check Expressions
+
+The `check` field contains a **pseudo-code expression** that describes the gate's condition logic. It is not executable code — it is precise documentation:
+
+```yaml
+# Good: clear and implementable
+check: project.members.some(m => m.userId === req.user.id && m.role === 'admin')
+
+# Bad: too vague
+check: user is admin
+
+# Bad: too implementation-specific
+check: await db.query('SELECT * FROM project_members WHERE...')
+```
+
+The check should be specific enough that a developer can implement it from reading the expression, but abstract enough that it does not depend on a particular ORM or database.
+
+## Gate Chains
+
+Gates chain through the `requires` field. When a route specifies `[^authenticated, ^project-admin]`, the gates are checked in order:
+
+1. `^authenticated` runs first. If it fails, the request is rejected (in HTTP, this is a 401 Unauthorized; other disciplines handle failure differently).
+2. `^project-admin` runs next (which itself requires `^authenticated`, already passed). If it fails, the request is denied (in HTTP, a 403 Forbidden).
+
+Chains prevent redundant checks. You never need to re-check authentication inside a role gate — the `requires` field guarantees it already passed.
+
+Deep chains are possible but should be kept shallow for clarity:
+```yaml
+^super-admin:
+  requires: [^authenticated, ^org-admin]  # ^org-admin itself requires ^authenticated
+```
+
+## The Effects Field
+
+Gates can trigger side effects when they pass, defined in the `effects` field:
+
+```yaml
+^first-purchase:
+  description: User is making their first purchase
+  check: user.purchaseCount === 0
+  type: state-precondition
+  requires: [^authenticated]
+  effects:
+    - id: first-purchase-badge
+      oneTime: true
+    - id: welcome-discount
+      oneTime: true
+```
+
+The `oneTime: true` flag ensures the effect triggers only once per user. Effects are useful for gamification, onboarding rewards, and analytics events. If a gate has no side effects, use `effects: []`.
+
+## Implementing Gates
+
+While `portal.yaml` defines *what* gates exist and *where* they apply, your application code must *implement* them. In web applications, the typical pattern is middleware (other disciplines use different enforcement mechanisms):
+
+```typescript
+// Express middleware implementing ^authenticated
+function authenticated(req, res, next) {
+  if (!req.session?.userId) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+  next();
+}
+
+// Express middleware implementing ^project-admin
+function projectAdmin(req, res, next) {
+  const project = await Project.findById(req.params.id);
+  if (!project.admins.includes(req.user.id)) {
+    return res.status(403).json({ error: 'Admin access required' });
+  }
+  next();
+}
+
+// Route applying the gate chain from portal.yaml
+router.put('/api/projects/:id', authenticated, projectAdmin, updateProject);
+```
+
+The key discipline: the `portal.yaml` definition and the implementation must match. If `portal.yaml` says an operation requires `^project-admin`, the code must actually enforce that check.

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

@@ -0,0 +1,133 @@
+---
+id: N-para-201-portal-protocol
+title: The Portal Protocol
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - specification-before-implementation
+  - four-steps-ask
+  - paradigmgatesforroute-suggests-gates
+symbols: []
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Specification Before Implementation
+
+The Portal Protocol is Paradigm's prescribed workflow for adding guarded operations. Its core principle is **specification before implementation** — you define what conditions must be met before you write the handler code. This inverts the common (and dangerous) pattern of building functionality first and bolting on checks later.
+
+The idea is universal: define what gates an operation needs before you implement the operation itself. In a web API, this means defining route gates before writing handlers. In a mobile app, it might mean specifying which screens require which conditions before building the UI. In a CLI tool, it means declaring what preconditions a command requires before writing the command logic.
+
+## The Four Steps
+
+### Step 1: Ask Paradigm
+
+Before writing any handler, call `paradigm_gates_for_route` with the route and method:
+
+```
+paradigm_gates_for_route({ route: "/api/projects/:id/members", method: "POST" })
+```
+
+This tool analyzes your existing `portal.yaml` and suggests gates based on patterns:
+- The route is under `/api/` → probably needs `^authenticated`
+- It modifies a project resource → probably needs `^project-admin` or `^project-member`
+- It is a POST (mutation) → higher gate requirements than a GET
+
+The suggestions are not binding, but they catch common oversights. You might realize you need a gate you had not considered.
+
+### Step 2: Add to portal.yaml
+
+Add the route with its required gates:
+
+```yaml
+routes:
+  # Existing routes...
+  "POST /api/projects/:id/members": [^authenticated, ^project-admin]
+```
+
+If you need a new gate that does not exist yet, define it in the `gates` section:
+
+```yaml
+gates:
+  ^project-admin:
+    description: User must be an admin of the project
+    check: project.admins.includes(req.user.id)
+    type: role
+    requires: [^authenticated]
+    effects: []
+```
+
+### Step 3: Implement the Gate Checks
+
+Write the middleware or handler code that enforces each gate. The implementation must match the `check` expression in portal.yaml. How a failed gate manifests depends on your discipline:
+
+- **Web APIs** return HTTP status codes (401 for failed identity checks, 403 for failed authorization)
+- **Mobile apps** might disable UI elements or show an upgrade prompt
+- **CLI tools** might exit with a specific error code and message
+- **Desktop apps** might gray out menu items or show a dialog
+
+Here is an example for a web API:
+
+```typescript
+async function projectAdmin(req, res, next) {
+  const project = await Project.findById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: 'Project not found' });
+  }
+  if (!project.admins.includes(req.user.id)) {
+    log.gate('^project-admin').warn('Access denied', {
+      userId: req.user.id,
+      projectId: req.params.id
+    });
+    return res.status(403).json({ error: 'Admin access required' });
+  }
+  req.project = project;  // Attach for downstream use
+  next();
+}
+```
+
+Notice the Paradigm logger usage: `log.gate('^project-admin').warn(...)` for a denied gate.
+
+### Step 4: Test Gate Failures
+
+Verify that failing a gate produces the correct behavior. In a web API, this means testing rejection status codes:
+
+```typescript
+it('rejects non-admin attempting to add member', async () => {
+  const res = await request(app)
+    .post('/api/projects/proj_123/members')
+    .set('Authorization', `Bearer ${memberToken}`)  // member, not admin
+    .send({ email: 'newuser@example.com' });
+
+  expect(res.status).toBe(403);
+});
+```
+
+Test both the pass path (authorized user succeeds) and the fail path (unauthorized user is rejected). The concept of pass/fail is universal across all disciplines — only the specific failure response varies.
+
+## Common Gate Patterns
+
+Over time, projects develop recurring gate patterns:
+
+| Pattern | Gate Name | Check |
+|---------|-----------|-------|
+| Any logged-in user | `^authenticated` | `req.user != null` |
+| Resource membership | `^{resource}-member` | `resource.members.includes(req.user.id)` |
+| Resource admin | `^{resource}-admin` | `resource.admins.includes(req.user.id)` |
+| Resource creator | `^{resource}-creator` | `resource.createdBy === req.user.id` |
+| Item author | `^{item}-author` | `item.authorId === req.user.id` |
+| Feature flag | `^feature-{name}` | `features.isEnabled(name, req.user)` |
+
+These patterns are reusable across projects. When you call `paradigm_gates_for_route`, the tool draws from these patterns to make suggestions.
+
+## The Cost of Skipping the Protocol
+
+The Portal Protocol makes conditions a first thought rather than an afterthought. By defining gates in portal.yaml before writing handlers, you create an auditable specification that is separate from (and checkable against) the implementation. Whether you are protecting API endpoints, gating CLI commands, or controlling feature access in a mobile app, the principle is the same: specify first, implement second.

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

@@ -0,0 +1,159 @@
+---
+id: N-para-201-signal-patterns
+title: Signal Patterns
+type: note
+author: paradigm
+created: '2026-04-22'
+updated: '2026-04-22'
+tags:
+  - course
+  - para-201
+  - business-signals-domain
+  - system-signals-infrastructure
+  - security-signals-auth
+symbols: []
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+category: paradigm-core
+origin: imported
+source: courses/para-201.json
+---
+
+## Events That Drive Side Effects
+
+Signals (`!`) are Paradigm's mechanism for documenting **decoupled communication**. When a component emits a signal, it announces that something happened without caring who listens. This decoupling is fundamental to maintainable systems — the payment service should not know about the email service, the analytics tracker, or the loyalty points calculator. It just announces `!payment-completed` and moves on.
+
+## Signal Categories
+
+### Business Signals
+
+Business signals represent **domain events** — things that matter to the business:
+
+```yaml
+!order-placed:
+  description: A new order has been successfully created
+  emitters: ["#order-service"]
+  category: business
+  data:
+    orderId: string
+    userId: string
+    total: number
+
+!subscription-renewed:
+  description: A recurring subscription payment succeeded
+  emitters: ["#billing-service"]
+  category: business
+
+!user-upgraded:
+  description: User upgraded from free to paid plan
+  emitters: ["#plan-service"]
+  category: business
+```
+
+Business signals are the most important category. They define the key moments in your application's lifecycle. If you had to explain your system to a new team member, you would list these events.
+
+### System Signals
+
+System signals represent **infrastructure events** — things that matter to operations:
+
+```yaml
+!cache-invalidated:
+  description: A cache entry or cache region was cleared
+  emitters: ["#cache-manager"]
+  category: system
+  data:
+    region: string
+    reason: string
+
+!database-failover:
+  description: Primary database failed, switched to replica
+  emitters: ["#database-pool"]
+  category: system
+  severity: warn
+
+!rate-limit-exceeded:
+  description: A user or IP exceeded the API rate limit
+  emitters: ["#rate-limiter"]
+  category: system
+```
+
+System signals are consumed by monitoring, alerting, and health-check systems rather than by business logic.
+
+### Security Signals
+
+Security signals represent **authentication and authorization events**:
+
+```yaml
+!login-failed:
+  description: User provided invalid credentials
+  emitters: ["#auth-handler"]
+  category: security
+  data:
+    email: string
+    reason: string
+    ipAddress: string
+
+!permission-denied:
+  description: Authenticated user tried to access a resource they lack permission for
+  emitters: ["#gate-middleware"]
+  category: security
+
+!suspicious-activity:
+  description: Unusual access pattern detected (multiple failed logins, geographic anomaly)
+  emitters: ["#security-monitor"]
+  category: security
+  severity: error
+```
+
+Security signals are critical for audit trails and intrusion detection. They should always include enough data to reconstruct what happened.
+
+## Emitters and Listeners
+
+Every signal has one or more **emitters** — the components that fire the event:
+
+```yaml
+!payment-completed:
+  emitters: ["#payment-service", "#manual-charge-handler"]
+```
+
+Listeners are not defined on the signal itself — they are documented on the listening component:
+
+```yaml
+#email-service:
+  description: Sends transactional emails
+  listens: ["!payment-completed", "!user-created", "!password-reset-requested"]
+```
+
+This asymmetry is intentional. The emitter must know it is emitting (so it is declared on the signal). But the listener can be added or removed without changing the signal definition — true decoupling.
+
+## Signals for Decoupled Side Effects
+
+The power of signals is in the side effects they enable without direct coupling:
+
+```
+!order-placed is emitted by #order-service
+  → #email-service listens → sends confirmation email
+  → #analytics-tracker listens → records conversion event
+  → #loyalty-service listens → awards loyalty points
+  → #inventory-service listens → decrements stock
+```
+
+The order service knows nothing about these four listeners. You can add a fifth listener (say, `#slack-notifier`) without touching the order service at all. This is the architectural benefit of signal-based communication.
+
+## The Data Field
+
+Signals can declare a `data` schema describing the payload emitted with the event:
+
+```yaml
+!user-created:
+  description: A new user account was registered
+  emitters: ["#auth-handler"]
+  category: business
+  data:
+    userId: string
+    email: string
+    registrationSource: string
+```
+
+The data field is documentation, not runtime validation. It tells listeners what to expect in the event payload, reducing the need to read the emitter's source code.