@plumbus/core 0.1.0

package/instructions/flows.md

@@ -0,0 +1,114 @@
+# Flows
+
+A flow is a multi-step workflow that orchestrates capabilities in sequence, with support for branching, parallel execution, waits, and delays.
+
+## Defining a Flow
+
+```ts
+import { defineFlow } from "@plumbus/core";
+import { z } from "zod";
+
+export const refundApproval = defineFlow({
+  name: "refundApproval",
+  domain: "billing",
+
+  input: z.object({ refundId: z.string(), amount: z.number() }),
+  state: z.object({ approved: z.boolean().default(false) }),
+
+  steps: [
+    { type: "capability", name: "validateRefund" },
+    { type: "conditional", name: "checkAmount", if: "amount > 100", then: "managerApproval", else: "autoApprove" },
+    { type: "wait", name: "managerApproval", event: "refund.approved" },
+    { type: "capability", name: "autoApprove" },
+    { type: "capability", name: "processRefund" },
+    { type: "eventEmit", name: "notifyCustomer", event: "refund.completed" },
+  ],
+
+  trigger: { event: "refund.requested" },
+  retry: { attempts: 3, backoff: "exponential" },
+});
+```
+
+## Step Types
+
+| Type | Purpose | Key Fields |
+|------|---------|-----------|
+| `capability` | Execute a named capability | `name` (capability name) |
+| `conditional` | Branch based on condition | `if`, `then`, `else` |
+| `wait` | Pause until event or timeout | `event` |
+| `delay` | Pause for a fixed duration | `duration` (e.g., `"24h"`, `"5m"`) |
+| `parallel` | Run multiple steps concurrently | `branches` (step names) |
+| `eventEmit` | Emit a framework event | `event` (event type) |
+### Conditional Syntax
+
+The `if` field accepts a JavaScript-like expression string. You can reference the flow `input` and `state` directly:
+
+```ts
+// Simple comparison against input
+{ type: "conditional", name: "checkAmount", if: "input.amount > 100", then: "managerApproval", else: "autoApprove" }
+
+// Reference flow state
+{ type: "conditional", name: "checkApproval", if: "state.approved", then: "processRefund", else: "escalate" }
+
+// Logical operators
+{ type: "conditional", name: "checkBoth", if: "input.amount > 100 && state.retryCount < 3", then: "retry", else: "fail" }
+```
+
+The `then` and `else` values reference step **names** within the same flow. Execution jumps to the named step.
+
+### Parallel Branches
+
+```ts
+{ type: "parallel", name: "notifyAll", branches: ["sendEmail", "sendSms", "logAudit"] }
+```
+
+All branches execute concurrently. The flow waits for **all** branches to complete before advancing. If any branch fails, the entire parallel step fails.
+## State Management
+
+Flows maintain a `state` object persisted across steps. Each step can read and modify state through the flow execution context.
+
+```ts
+state: z.object({
+  approved: z.boolean().default(false),
+  reviewerId: z.string().optional(),
+  retryCount: z.number().default(0),
+})
+```
+
+## Triggers
+
+### Event-triggered
+```ts
+trigger: { event: "order.placed" }
+```
+When the named event fires, a new flow execution starts with the event payload mapped to the flow input.
+
+### Scheduled
+```ts
+schedule: { cron: "0 9 * * MON" }   // Every Monday at 9 AM
+```
+
+### Manual
+```ts
+// From a capability handler:
+await ctx.flows.start("refundApproval", { refundId: "rf_123", amount: 150 });
+```
+
+## Retry Policy
+
+```ts
+retry: {
+  attempts: 3,        // Max retry attempts per failed step
+  backoff: "exponential"  // "exponential" or "fixed"
+}
+```
+
+Steps that fail with transient errors are retried. Permanent failures stop the flow and move it to the dead-letter queue.
+
+## Flow Lifecycle
+
+`created → running → waiting → running → completed | failed`
+
+- Steps execute sequentially (except `parallel`)
+- Every step produces an audit record
+- Failed flows with exhausted retries land in a dead-letter queue for manual inspection

package/instructions/framework.md

@@ -0,0 +1,86 @@
+# Plumbus Framework
+
+Plumbus is an AI-native, contract-driven TypeScript application framework. You build applications by composing five primitives — **Entities**, **Capabilities**, **Flows**, **Events**, and **Prompts** — through a controlled execution context (`ctx`).
+
+## Core Abstractions
+
+| Primitive | Purpose | Defined with |
+|-----------|---------|--------------|
+| **Entity** | Data model with classification, retention, relations | `defineEntity()` |
+| **Capability** | Discrete unit of business logic (query, action, job, event handler) | `defineCapability()` |
+| **Flow** | Multi-step workflow orchestrating capabilities | `defineFlow()` |
+| **Event** | Domain fact emitted by capabilities, consumed by handlers/flows | `defineEvent()` |
+| **Prompt** | AI interaction template with typed input/output | `definePrompt()` |
+
+## Execution Context (`ctx`)
+
+Every capability handler receives `ctx` — the scoped runtime context:
+
+| Property | Purpose |
+|----------|---------|
+| `ctx.auth` | Authenticated identity — userId, roles, scopes, tenantId |
+| `ctx.data` | Entity repositories — `ctx.data.User.findById(id)` |
+| `ctx.events` | Event emission — `ctx.events.emit("order.placed", payload)` |
+| `ctx.flows` | Flow orchestration — `ctx.flows.start("processRefund", input)` |
+| `ctx.ai` | AI operations — generate, extract, classify, retrieve |
+| `ctx.audit` | Audit logging — `ctx.audit.record("user.updated", meta)` |
+| `ctx.errors` | Structured errors — validation, notFound, forbidden, conflict, internal |
+| `ctx.logger` | Structured logging — info, warn, error |
+| `ctx.time` | Time utilities — `ctx.time.now()` |
+| `ctx.config` | Read-only application configuration |
+| `ctx.security` | Security service — policy evaluation and access enforcement |
+
+## How Subsystems Connect
+
+1. **Capabilities** are the only entry points for business logic. HTTP routes are auto-generated from capability contracts.
+2. **Entities** provide typed data access via repositories injected on `ctx.data`.
+3. **Events** are emitted inside capabilities (`ctx.events.emit`), persisted via the outbox pattern (same transaction as data), then dispatched to consumers.
+4. **Flows** orchestrate multiple capabilities in sequence, with support for conditional branching, parallel execution, waits, and delays. Flows can be triggered by events or cron schedules.
+5. **Prompts** provide structured AI interactions. Capabilities invoke AI via `ctx.ai.generate({ prompt: "promptName", input })`.
+6. **Security** is deny-by-default. Every capability declares an `access` policy. The framework evaluates it against `ctx.auth` before executing the handler.
+7. **Audit** records are automatically created for capability executions, data mutations, and AI invocations.
+8. **Governance** rules analyze the entire system (entities, capabilities, flows, events, prompts) and produce advisory signals — warnings, not blockers.
+
+## Project Structure
+
+```
+app/
+  capabilities/<domain>/<name>/
+    capability.ts     # Contract (defineCapability)
+    impl.ts           # Handler implementation
+    tests/            # Tests
+  flows/<domain>/<name>/
+    flow.ts           # Contract (defineFlow)
+    tests/
+  entities/
+    <name>.entity.ts  # Entity definition
+  events/
+    <name>.event.ts   # Event definition
+  prompts/
+    <name>.prompt.ts  # Prompt definition
+config/
+  app.config.ts       # PlumbusConfig
+  ai.config.ts        # AI provider configuration
+```
+
+## Framework-Provided Dependencies
+
+The framework provides common dependencies — **consumer apps must NOT install them separately**. Import through the framework's subpath exports:
+
+| Dependency | Import from | Usage |
+|-----------|-------------|-------|
+| **Zod** | `@plumbus/core/zod` | `import { z } from "@plumbus/core/zod"` |
+| **Vitest** | `@plumbus/core/testing` | `import { describe, it, expect } from "@plumbus/core/testing"` |
+| **Playwright** | `@plumbus/core/testing` | `import { chromium } from "@plumbus/core/testing"` |
+| **Vitest Config** | `@plumbus/core/vitest` | `import { defineConfig } from "@plumbus/core/vitest"` |
+
+**CRITICAL**: Never add `zod`, `vitest`, `playwright`, or `@playwright/test` to a consumer app's `package.json`. They are provided by `@plumbus/core`.
+
+### CLI Commands
+
+| Task | Command |
+|------|---------|
+| Run tests | `plumbus test` |
+| Watch mode | `plumbus test --watch` |
+| Run e2e tests | `plumbus test --config frontend/e2e/vitest.config.e2e.ts` |
+| Dev server | `plumbus dev` |

package/instructions/governance.md

@@ -0,0 +1,78 @@
+# Governance
+
+Plumbus governance is **advisory, not blocking** — "guardrails, not gates." Rules produce warnings that inform developers; they don't prevent deployment.
+
+## Governance Signals
+
+```ts
+{
+  severity: "warning",                    // "info" | "warning" | "high"
+  rule: "security.missing-access-policy",
+  description: "Capability 'deleteUser' has no access policy",
+  affectedComponent: "capabilities/users/deleteUser",
+  remediation: "Add an access policy to restrict who can delete users"
+}
+```
+
+## Built-in Rules
+
+### Security
+- Capabilities without access policies
+- Overly permissive roles (e.g., `public: true` on mutations)
+- Missing tenant isolation on multi-tenant entities
+- Cross-tenant data access patterns
+
+### Privacy
+- `highly_sensitive` fields stored without `encrypted: true`
+- Personal data fields without `maskedInLogs: true`
+- Missing `classification` on entity fields
+- Excessive data retention durations
+
+### Architecture
+- Capabilities with too many side effects
+- Flows with excessive branching depth
+- Large handler implementations (complexity warning)
+
+### AI
+- Prompts receiving sensitive classified data
+- Missing output validation schemas
+- Prompts without model configuration
+
+## Running Governance Checks
+
+```bash
+plumbus verify              # Run all rules, human-readable output
+plumbus verify --json       # Machine-readable output
+```
+
+Exit code is non-zero if any `high` severity signals are found.
+
+## Overrides
+
+When a governance warning is acknowledged and accepted:
+
+```yaml
+# app/compliance/overrides/delete-user-public.yaml
+rule: security.missing-access-policy
+justification: "This is an internal admin tool with network-level access control"
+author: "jane@company.com"
+timestamp: "2026-01-15T10:30:00Z"
+```
+
+Overrides appear in governance reports as acknowledged deviations.
+
+## Policy Profiles
+
+Assess compatibility with compliance frameworks:
+
+```bash
+plumbus certify policy gdpr
+plumbus certify policy pci_dss
+plumbus certify policy soc2
+plumbus certify policy hipaa
+```
+
+Each profile defines rules specific to that standard. Reports include:
+- Compatibility score (0-100%)
+- Per-rule pass/partial/fail/override results
+- Remediation recommendations

package/instructions/patterns.md

@@ -0,0 +1,107 @@
+# Patterns & Conventions
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Capability | camelCase verb+noun | `getUser`, `approveRefund`, `processPayment` |
+| Entity | PascalCase noun | `User`, `Order`, `InvoiceLine` |
+| Event | domain.pastTense | `order.placed`, `refund.requested`, `user.updated` |
+| Flow | camelCase noun | `refundApproval`, `orderFulfillment` |
+| Prompt | camelCase verb+noun | `summarizeTicket`, `classifyIntent` |
+| Domain | lowercase singular | `users`, `billing`, `fulfillment` |
+
+## File Structure
+
+```
+app/capabilities/<domain>/<name>/
+  capability.ts     # defineCapability() — contract only
+  impl.ts           # handler implementation (optional split)
+  tests/
+    <name>.test.ts
+    fixtures/
+
+app/flows/<domain>/<name>/
+  flow.ts
+  tests/
+
+app/entities/<name>.entity.ts
+app/events/<name>.event.ts
+app/prompts/<name>.prompt.ts
+```
+
+## Do's
+
+- **Do** declare all side effects in `effects`. Governance relies on this.
+- **Do** add `classification` to every entity field that contains user data.
+- **Do** use `maskedInLogs: true` for passwords, tokens, and keys.
+- **Do** keep handlers thin — delegate complex logic to helper functions.
+- **Do** use `ctx.errors.*` for all error conditions (not raw `throw new Error`).
+- **Do** write tests using `runCapability` and `simulateFlow` test utilities.
+- **Do** use the outbox pattern for events — always emit via `ctx.events.emit`.
+- **Do** add `tenantScoped: true` to entities that require multi-tenant isolation.
+
+## Don'ts
+
+- **Don't** access the database directly — always use `ctx.data.<Entity>`.
+- **Don't** emit events outside of capabilities — the outbox pattern requires a capability transaction.
+- **Don't** bypass `ctx.auth` checks — the framework evaluates access policies before your handler runs.
+- **Don't** mutate the `ctx` object — it is scoped and controlled by the framework.
+- **Don't** import framework internals — use only the public SDK surface (`defineCapability`, `defineFlow`, etc.).
+- **Don't** store secrets in code — use `ctx.config` and environment variables.
+- **Don't** edit files in `.plumbus/generated/` — they are regenerated on every build.
+- **Don't** create capabilities without access policies (governance will warn).
+
+## Common Patterns
+
+### CRUD Capability Set
+
+For a typical entity, create four capabilities:
+
+```ts
+// app/capabilities/users/getUser/capability.ts
+defineCapability({ name: "getUser", kind: "query", ... });
+
+// app/capabilities/users/createUser/capability.ts
+defineCapability({ name: "createUser", kind: "action", ... });
+
+// app/capabilities/users/updateUser/capability.ts
+defineCapability({ name: "updateUser", kind: "action", ... });
+
+// app/capabilities/users/deleteUser/capability.ts
+defineCapability({ name: "deleteUser", kind: "action", ... });
+```
+
+### Event-Driven Side Effects
+
+Instead of calling multiple services in one capability, emit events and let handlers react:
+
+```ts
+// Capability: createOrder
+handler: async (ctx, input) => {
+  const order = await ctx.data.Order.create(input);
+  await ctx.events.emit("order.placed", { orderId: order.id });
+  return { orderId: order.id };
+}
+
+// Separate event handlers react independently:
+// onOrderPlaced → create shipment
+// onOrderPlaced → send confirmation email
+// onOrderPlaced → update analytics
+```
+
+### AI-Augmented Capability
+
+```ts
+handler: async (ctx, input) => {
+  const classification = await ctx.ai.classify({
+    labels: ["billing", "technical", "general"],
+    text: input.message,
+  });
+  const ticket = await ctx.data.Ticket.create({
+    ...input,
+    category: classification[0],
+  });
+  return { ticketId: ticket.id, category: classification[0] };
+}
+```

package/instructions/security.md

@@ -0,0 +1,79 @@
+# Security Model
+
+Plumbus uses a **deny-by-default** security model. Every capability must declare its access policy explicitly.
+
+## Access Policies
+
+```ts
+access: {
+  roles: ["admin", "billing"],     // Required roles (any match)
+  scopes: ["refunds:write"],       // Required scopes (all must match)
+  public: false,                    // If true, no auth required
+  tenantScoped: true,              // Enforce tenant isolation
+  serviceAccounts: ["payment-svc"], // Allow service-to-service auth
+}
+```
+
+### Evaluation Order
+1. If `public: true` → allow
+2. Authenticate identity → populate `ctx.auth`
+3. Check `roles` — user must have at least one matching role
+4. Check `scopes` — user must have all required scopes
+5. If `tenantScoped: true` — verify `ctx.auth.tenantId` matches target data
+6. Check `serviceAccounts` — for service-to-service calls
+
+If any check fails → **403 Forbidden** with audit record.
+
+## Auth Context (`ctx.auth`)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `userId` | string? | Authenticated user ID |
+| `roles` | string[] | User's assigned roles |
+| `scopes` | string[] | User's permission scopes |
+| `tenantId` | string? | Tenant the user belongs to |
+| `provider` | string | Auth provider (e.g., "oidc", "auth0") |
+| `sessionId` | string? | Session identifier |
+| `authenticatedAt` | Date? | When authentication occurred |
+
+## Tenant Isolation
+
+When `tenantScoped: true`:
+- All repository queries automatically inject `WHERE tenantId = ctx.auth.tenantId`
+- Cross-tenant data access is blocked at the framework level
+- Events carry `tenantId` and are only delivered to matching consumers
+
+## Field Classification & Edit Zones
+
+Entity fields with `classification: "sensitive"` or `"highly_sensitive"`:
+- Are masked in logs and audit records
+- Trigger governance warnings if used in AI prompts
+- Can be flagged for encryption at rest
+
+### Edit Zones
+
+| Zone | Description |
+|------|-------------|
+| **Safe** | Application code in `app/` — capabilities, flows, entities, events, prompts |
+| **Restricted** | Configuration files in `config/` — changes may affect security posture |
+| **Forbidden** | Framework internals, generated code in `.plumbus/generated/` |
+
+## Authentication Adapters
+
+Plumbus uses pluggable auth adapters. The default is JWT validation. The adapter normalizes tokens into `AuthContext`:
+
+- JWT (default) — validates JWT tokens, extracts claims
+- Auth0, Clerk, Cognito — provider-specific adapters (community)
+- Custom — implement the adapter interface
+
+## Password Utilities
+
+When building first-party email/password authentication, use the framework helpers instead of app-local crypto:
+
+```ts
+import { hashPassword, verifyPassword } from "@plumbus/core";
+```
+
+- `hashPassword(password)` stores credentials as `salt:hash` using Node.js `scrypt`
+- `verifyPassword(password, storedHash)` performs a timing-safe comparison
+- Store only the returned hash string in entity fields marked `classification: "highly_sensitive"`