mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-animations-engine.md

@@ -0,0 +1,78 @@
+---
+id: concept-animations-engine
+title: `animations` engine (preferred)
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# `animations` engine
+
+The animation engine — cross-platform (web + RN), reduced-motion aware,
+integrates with the 5-level cascade. Use `animations` instead of legacy
+`motion` for new specs.
+
+## Shape / Signature
+
+```json
+"animations": {
+  "mount":   { "recipe": "fade-up" },
+  "hover":   { "recipe": "lift" },
+  "active":  { "recipe": "pop" },
+  "ambient": { "recipe": "breathe-subtle" },
+  "stateChange": { "watch": "/cart/count", "on": "increase", "recipe": "pop", "duration": 300 }
+}
+```
+
+## Per-trigger forms
+
+```json
+"animations": {
+  "mount": { "recipe": "fade-up" }                                   // single recipe
+  "mount": { "recipe": "fade-up", "duration": 400, "delay": 100 }     // recipe with overrides
+  "mount": [{ "recipe": "fade" }, { "recipe": "scale-in" }]           // array — parallel animations
+  "mount": null                                                       // disable inherited animation
+  "mount": { "keyframes": [...] }                                     // inline animation, no recipe
+}
+```
+
+## 7 triggers
+
+`mount`, `unmount`, `hover`, `focus`, `active`, `ambient`, `stateChange`.
+See [[@concept-animation-triggers]].
+
+## 15 recipes
+
+`fade`, `fade-up`, `fade-down`, `scale-in`, `slide-left`, `slide-right`,
+`lift`, `glow`, `pulse-primary`, `breathe-subtle`, `shimmer`, `float`,
+`pop`, `shake`, `spin`. See [[@concept-animation-recipes]].
+
+## Caps
+
+- Per-trigger: soft 3 (warn), hard 6 (error).
+- Per-element: soft 5 triggers (warn), hard 7 (error — all triggers filled).
+
+See [[@concept-animation-caps]].
+
+## Cascade
+
+`identity → variant → elementDef → template → element` — see
+[[@concept-animation-cascade]] for full merge semantics including
+null-disable.
+
+## Related concepts
+
+- [[@concept-animation-triggers]]
+- [[@concept-animation-recipes]]
+- [[@concept-animation-cascade]]
+- [[@concept-animation-null-semantics]]
+- [[@concept-state-change-animation]]
+- [[@concept-reduced-motion]]
+- [[@concept-animation-caps]]
+- [[@concept-keyframe-snapshot]]
+- [[@concept-web-only-recipes]]
+- [[@concept-motion-field]] — legacy alternative
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations → Animation engine`
+- `docs/consumer/reference-doc.md § Animation System` (rules 180-200)

package/docs/wiki/compiled/concept-api-audit.md

@@ -0,0 +1,67 @@
+---
+id: concept-api-audit
+title: `audit` — auto-inject user + timestamp
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoints, docs/consumer/reference-doc.md#audit-sp3]
+---
+
+# `audit` — auto-inject user + timestamp
+
+Endpoint-level config that auto-injects `username` and `timestamp` into
+CRUD INSERT and UPDATE operations. **Audit values override client-sent
+values** — prevents spoofing.
+
+## Shape
+
+```json
+"endpoints": {
+  "items": {
+    "path": "/api/items",
+    "crud": { "table": "Items", "primaryKey": "id", "insertable": ["name"], "updatable": ["name"] },
+    "audit": {
+      "createdBy": "usuarioCreacion",
+      "createdAt": "fechaCreacion",
+      "updatedBy": "usuarioModificacion",
+      "updatedAt": "fechaModificacion",
+      "timezone": "America/El_Salvador"
+    }
+  }
+}
+```
+
+All audit fields optional — only configured fields are injected.
+
+## Behavior per operation
+
+| Operation | Fields injected |
+|---|---|
+| **INSERT** | `createdBy` + `createdAt` + `updatedBy` + `updatedAt` |
+| **UPDATE** | `updatedBy` + `updatedAt` |
+| **DELETE** | None |
+
+Source: `req.user.username` (from JWT) + framework timestamp.
+
+## Timezone
+
+- Without `timezone` → UTC (default).
+- With `timezone` → IANA string (e.g., `"America/El_Salvador"`,
+  `"America/Tegucigalpa"`, `"US/Eastern"`).
+- Use timezone when the database stores local time (most enterprise DBs).
+- Uses `Intl.DateTimeFormat` — works regardless of server location.
+
+## Security guarantees
+
+- Audit values **override** client-sent values (even if client tries to
+  spoof) — bypasses `filterFields`.
+- No username available (public endpoint) → only timestamp fields injected.
+
+## Related concepts
+
+- [[@concept-api-crud-endpoint]]
+- [[@concept-api-auth]]
+- [[@concept-api-scope-filter]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoints → Audit properties`
+- `docs/consumer/reference-doc.md § Audit (SP3)`

package/docs/wiki/compiled/concept-api-auth.md

@@ -0,0 +1,67 @@
+---
+id: concept-api-auth
+title: API auth (`auth` block)
+kind: concept
+sources: [docs/consumer/ai-context-api.md#auth]
+---
+
+# API auth
+
+`auth` block in ApiSpec defines the auth strategy, claims mapping,
+provider, policies, and scope filter.
+
+## Shape
+
+```json
+"auth": {
+  "strategy": "jwt",
+  "claims": { "username": "sub", "roles": "roles", "scope": "institutions" },
+  "provider": {
+    "usersTable": "Users",
+    "usernameColumn": "username",
+    "passwordColumn": "password",
+    "passwordHash": "bcrypt",
+    "activeCondition": "active = 1",
+    "rolesQuery": "SELECT role AS val FROM UserRoles WHERE username = @username",
+    "scopeQuery": "SELECT institution_id AS val FROM UserInstitutions WHERE username = @username"
+  },
+  "policies": {
+    "items": { "roles": ["ADMIN", "EDITOR"] },
+    "reports": { "roles": ["ADMIN", "VIEWER"] },
+    "admin": { "roles": ["ADMIN"] }
+  },
+  "scopeFilter": {
+    "claim": "institutions",
+    "type": "int",
+    "column": "institution_id",
+    "bypassRoles": ["ADMIN"]
+  }
+}
+```
+
+## Components
+
+| Component | Purpose |
+|---|---|
+| `claims` | Maps JWT claim names to your naming convention |
+| `provider` | Database-backed login: user table, password hash, role/scope queries |
+| `policies` | Named role lists referenced by endpoints via `policy` |
+| `scopeFilter` | Row-level security — see [[@concept-api-scope-filter]] |
+
+## Provider details
+
+- `passwordHash`: `"bcrypt"` (default) or `"argon2"`.
+- Provider queries use `@username` parameter.
+- Scope queries return `val` column.
+
+## Related concepts
+
+- [[@concept-api-spec]]
+- [[@concept-api-scope-filter]]
+- [[@concept-api-login-body-contract]]
+- [[@pattern-fullstack-coherence]] — alignment with AppSpec roleAccess
+- [[@cli-contract]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Auth`

package/docs/wiki/compiled/concept-api-catalogs.md

@@ -0,0 +1,44 @@
+---
+id: concept-api-catalogs
+title: API catalogs — dropdown sources
+kind: concept
+sources: [docs/consumer/ai-context-api.md#catalogs]
+---
+
+# API catalogs — dropdown sources
+
+Three catalog types for dropdown / picker data.
+
+## Types
+
+```json
+"catalogs": {
+  "years":        { "from": "TableName", "distinct": "year", "orderBy": "year DESC" },
+  "institutions": { "from": "Institution", "value": "id", "label": "name", "orderBy": "name" },
+  "categories":   { "from": "Categories", "value": "id", "label": "name", "extra": ["type"] },
+  "months":       { "static": [{ "label": "January", "value": "1" }, { "label": "February", "value": "2" }] }
+}
+```
+
+| Type | Props | Description |
+|---|---|---|
+| **DB distinct** | `from`, `distinct`, `orderBy` | Unique values from a column |
+| **DB value/label** | `from`, `value`, `label`, `extra?`, `orderBy?`, `where?` | Maps columns to `{ label, value }` options |
+| **Static** | `static` (array of `{label, value}`) | Hardcoded options |
+
+## Use in frontend
+
+Frontend `select` reads catalog via fetch:
+```json
+"options": { "$state": "/catalogs/months" }
+```
+
+## Related concepts
+
+- [[@concept-api-spec]]
+- [[@primitive-select]]
+- [[@cli-contract]] — validates frontend filter values match API catalogs
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Catalogs`

package/docs/wiki/compiled/concept-api-crud-endpoint.md

@@ -0,0 +1,90 @@
+---
+id: concept-api-crud-endpoint
+title: API CRUD endpoint — 1 declaration → 3 routes
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoints, docs/consumer/ai-context-runtime-semantics.md#31-crud--one-endpoint-three-routes--blocker-3]
+---
+
+# API CRUD endpoint
+
+A single endpoint with `crud: { table, primaryKey, insertable, updatable }`
+generates **three** routes automatically:
+
+- `POST <path>` — insert (body filtered to `insertable`)
+- `PUT <path>/:id` — update (body filtered to `updatable`, `:id` matches `primaryKey`)
+- `DELETE <path>/:id` — delete by primary key
+
+## Shape
+
+```json
+"items": {
+  "path": "/api/items",
+  "policy": "admin",
+  "crud": {
+    "table": "Items",
+    "primaryKey": "id",
+    "insertable": ["name", "amount", "categoryId"],
+    "updatable": ["name", "amount"]
+  },
+  "audit": {
+    "createdBy": "created_by", "createdAt": "created_at",
+    "updatedBy": "updated_by", "updatedAt": "updated_at",
+    "timezone": "America/El_Salvador"
+  }
+}
+```
+
+## `filterFields` security
+
+Fields in the request body NOT listed in `insertable` (POST) or `updatable`
+(PUT) are **silently dropped**. Security feature — clients cannot inject
+arbitrary columns (e.g., `isAdmin: true`).
+
+## Audit — un-spoofable
+
+Audit fields bypass `filterFields`. Server writes `req.user.username` +
+timestamp post-filter. Clients cannot forge `createdBy` / `updatedBy` /
+`createdAt` / `updatedAt`. CV4 in 2026-04 experiment validations —
+confirmed secure-by-design.
+
+## Constraints / Anti-patterns
+
+- **Don't combine `crud: {}` with `endpoint.path` ending `/:id`.** CRUD
+  auto-appends `/:id` to PUT/DELETE — `path: "/api/x/:id"` produces
+  `/api/x/:id/:id`. See [[@antipattern-crud-id-collision]] (also a
+  `mythik lint` rule with severity `error`).
+- **Don't declare 3 separate endpoints** with `crud: {}` each.
+  See [[@concept-api-endpoints-overview]] § Anti-pattern.
+
+## Read-only list endpoint stays separate
+
+```json
+"items-list": {
+  "path": "/api/items/query",
+  "policy": "items",
+  "scopeFilter": true,
+  "query": "SELECT id, name, amount, categoryId FROM Items ORDER BY name",
+  "pagination": "offset"
+}
+```
+
+(No `crud:{}` — uses SQL or handler.)
+
+## Trigger-safe queries
+
+INSERT uses `SCOPE_IDENTITY()` + SELECT instead of `OUTPUT INSERTED.*`.
+UPDATE uses SELECT after the update. Both compatible with SQL Server tables
+that have triggers (rule 67).
+
+## Related concepts
+
+- [[@concept-api-endpoints-overview]]
+- [[@concept-api-audit]]
+- [[@concept-api-scope-filter]]
+- [[@antipattern-crud-id-collision]]
+- [[@cli-lint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § CRUD endpoint`
+- `docs/consumer/ai-context-runtime-semantics.md § 3.1`

package/docs/wiki/compiled/concept-api-endpoint-properties.md

@@ -0,0 +1,40 @@
+---
+id: concept-api-endpoint-properties
+title: API endpoint properties (full table)
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoint-properties]
+---
+
+# API endpoint properties
+
+| Property | Type | Description |
+|---|---|---|
+| `path` | string | URL path (supports `:id` params) |
+| `method` | string | `GET` (default), `POST`, `PUT`, `DELETE` |
+| `query` | string | SQL query (mutually exclusive with `handler`) |
+| `handler` | string | Handler file name (mutually exclusive with `query`) |
+| `crud` | object | `{ table, primaryKey, insertable, updatable }` |
+| `pagination` | `"offset"` \| `false` | Enable offset pagination |
+| `totals` | string[] | Aggregate expressions: `"SUM:column"`, `"COUNT:*"` |
+| `params` | object | Parameter definitions (see [[@concept-api-param-properties]]) |
+| `policy` | string | Reference to `auth.policies` key, or `"public"` |
+| `scopeFilter` | boolean/object | Enable row-level filtering |
+| `audit` | object | Auto-inject user + timestamp fields |
+
+## Constraints
+
+- `query` and `handler` are mutually exclusive.
+- `crud` cannot combine with `path` ending in `/:id`.
+
+## Related concepts
+
+- [[@concept-api-spec]]
+- [[@concept-api-endpoints-overview]]
+- [[@concept-api-param-properties]]
+- [[@concept-api-auth]]
+- [[@concept-api-scope-filter]]
+- [[@concept-api-audit]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoint properties`

package/docs/wiki/compiled/concept-api-endpoints-overview.md

@@ -0,0 +1,57 @@
+---
+id: concept-api-endpoints-overview
+title: API endpoints — 4 patterns
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoints]
+---
+
+# API endpoints — 4 patterns
+
+Four endpoint declaration patterns:
+
+| Pattern | Use | Article |
+|---|---|---|
+| Query | Simple SQL read | [[@concept-api-query-endpoint]] |
+| Handler | Complex logic | [[@concept-api-handler-endpoint]] |
+| CRUD | INSERT/UPDATE/DELETE for a table (1 endpoint → 3 routes) | [[@concept-api-crud-endpoint]] |
+| Public | No-auth endpoint (health checks) | [[@concept-api-public-endpoint]] |
+
+## Common properties
+
+See [[@concept-api-endpoint-properties]] for the full table.
+
+## Mutual exclusivity
+
+- `query` and `handler` are mutually exclusive — use `query` for simple
+  SQL, `handler` for complex logic.
+- CRUD declarations (`crud: {}`) generate POST + PUT/:id + DELETE/:id
+  automatically — DO NOT also declare separate POST/PUT/DELETE endpoints
+  for the same path.
+
+## Anti-pattern
+
+```json
+// WRONG — each crud:{} synthesizes 3 routes; 3 endpoints → 9 routes, collisions
+"item-create": { "path": "/api/items",     "method": "POST",   "crud": { } },
+"item-update": { "path": "/api/items/:id", "method": "PUT",    "crud": { } },
+"item-delete": { "path": "/api/items/:id", "method": "DELETE", "crud": { } }
+```
+
+The `PUT` endpoint at `/api/items/:id` combined with auto-append produces
+`/api/items/:id/:id` (broken). See [[@antipattern-crud-id-collision]] —
+also a `mythik lint` rule.
+
+## Related concepts
+
+- [[@concept-api-spec]]
+- [[@concept-api-query-endpoint]]
+- [[@concept-api-handler-endpoint]]
+- [[@concept-api-crud-endpoint]]
+- [[@concept-api-public-endpoint]]
+- [[@concept-api-endpoint-properties]]
+- [[@concept-api-param-properties]]
+- [[@antipattern-crud-id-collision]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoints`

package/docs/wiki/compiled/concept-api-handler-endpoint.md

@@ -0,0 +1,56 @@
+---
+id: concept-api-handler-endpoint
+title: API handler endpoint — complex logic
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoints]
+---
+
+# API handler endpoint
+
+Complex-logic endpoint backed by a handler module file. Use when SQL alone
+isn't enough.
+
+## Shape
+
+```json
+"advanced-report": {
+  "path": "/api/report",
+  "policy": "reports",
+  "handler": "report-handler",
+  "params": {
+    "year":     { "type": "int",    "source": "query" },
+    "search":   { "type": "string", "source": "query" },
+    "page":     { "type": "int",    "default": 0,  "source": "query" },
+    "pageSize": { "type": "int",    "default": 20, "max": 100, "source": "query" }
+  }
+}
+```
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `handler` | string | Handler file name (mutually exclusive with `query`) |
+| `policy` | string | Reference to `auth.policies` key |
+| `params` | object | Parameter definitions |
+
+## Mutual exclusivity
+
+`query` and `handler` are mutually exclusive — use `query` for simple
+SQL, `handler` for complex logic.
+
+## Handler discovery
+
+`packages/server/src/handler-loader.ts` discovers handler modules from the
+filesystem and validates references (`validateHandlerRefs`).
+
+## Related concepts
+
+- [[@concept-api-endpoints-overview]]
+- [[@concept-api-endpoint-properties]]
+- [[@concept-api-param-properties]]
+- [[@concept-customize-server-middleware]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoints → Handler endpoint`

package/docs/wiki/compiled/concept-api-login-body-contract.md

@@ -0,0 +1,47 @@
+---
+id: concept-api-login-body-contract
+title: `/api/auth/login` body contract
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#32-apiauthlogin-body-contract]
+---
+
+# `/api/auth/login` body contract
+
+The framework's `/api/auth/login` expects body `{ "username": string,
+"password": string }`. **Not `email`.** Maps to enterprise apps that use
+non-email username auth (employee ID, LDAP username, etc.).
+
+## Expected body
+
+```json
+{ "username": "alice", "password": "..." }
+```
+
+## Response on missing fields
+
+HTTP 400:
+```json
+{ "error": { "code": "VALIDATION_FAILED", "message": "username and password are required" } }
+```
+
+## Response on success
+
+JWT + refresh token shape (exact fields depend on provider config — check
+your `auth.provider` response shape).
+
+## Email-convention apps
+
+Use `loginBody` template at the spec level — see
+[[@pattern-login-body-template]]. The server validates against the users
+table's `usernameColumn`, which can be an email column.
+
+## Related concepts
+
+- [[@pattern-login-body-template]]
+- [[@concept-api-auth]]
+- [[@action-login]]
+- [[@pattern-login-screen]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 3.2`

package/docs/wiki/compiled/concept-api-param-properties.md

@@ -0,0 +1,44 @@
+---
+id: concept-api-param-properties
+title: API param properties
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoint-properties]
+---
+
+# API param properties
+
+| Property | Type / Values |
+|---|---|
+| `type` | `int` / `string` / `float` / `date` / `boolean` |
+| `required` | boolean |
+| `default` | any |
+| `max` | number (max value or max length) |
+| `source` | `query` / `path` / `body` |
+
+## `source` defaults
+
+Auto-detect:
+1. **Path** first (matches `:id` segment in `path`).
+2. **Body** for non-GET requests.
+3. **Query** as fallback.
+
+## Examples
+
+```json
+"params": {
+  "year":     { "type": "int", "source": "query" },
+  "search":   { "type": "string", "source": "query" },
+  "page":     { "type": "int", "default": 0, "source": "query" },
+  "pageSize": { "type": "int", "default": 20, "max": 100, "source": "query" }
+}
+```
+
+## Related concepts
+
+- [[@concept-api-endpoint-properties]]
+- [[@concept-api-query-endpoint]]
+- [[@concept-api-handler-endpoint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoint properties → Param properties`

package/docs/wiki/compiled/concept-api-public-endpoint.md

@@ -0,0 +1,33 @@
+---
+id: concept-api-public-endpoint
+title: API public endpoint (`policy: "public"`)
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoints]
+---
+
+# API public endpoint
+
+Endpoint that skips auth. Use **for health checks and public endpoints
+only**.
+
+## Shape
+
+```json
+"health": { "path": "/api/health", "policy": "public", "query": "SELECT 1 as status" }
+```
+
+## Constraints / Anti-patterns
+
+- `policy: "public"` skips auth — never use for endpoints that touch
+  user data or modify state.
+- Audit timestamp fields still inject (no username available — only
+  timestamp).
+
+## Related concepts
+
+- [[@concept-api-endpoints-overview]]
+- [[@concept-api-auth]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoints → Public endpoint`

package/docs/wiki/compiled/concept-api-query-endpoint.md

@@ -0,0 +1,53 @@
+---
+id: concept-api-query-endpoint
+title: API query endpoint — SQL-driven read
+kind: concept
+sources: [docs/consumer/ai-context-api.md#endpoints]
+---
+
+# API query endpoint
+
+SQL-driven read endpoint with optional pagination + totals.
+
+## Shape
+
+```json
+"item-list": {
+  "path": "/api/items",
+  "policy": "items",
+  "scopeFilter": true,
+  "query": "SELECT i.id, i.name, i.amount, c.name as category FROM Items i LEFT JOIN Categories c ON i.categoryId = c.id ORDER BY i.name",
+  "pagination": "offset",
+  "params": { "pageSize": { "type": "int", "default": 20, "max": 100 } },
+  "totals": ["SUM:amount", "COUNT:*"]
+}
+```
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `path` | string | URL path (supports `:id` params) |
+| `query` | string | SQL query (mutually exclusive with `handler`) |
+| `pagination` | `"offset"` \| `false` | Enable offset pagination |
+| `totals` | string[] | Aggregate expressions: `"SUM:column"`, `"COUNT:*"` |
+| `params` | object | Parameter definitions |
+| `policy` | string | Reference to `auth.policies` key, or `"public"` |
+| `scopeFilter` | boolean/object | Enable row-level filtering |
+
+## Response envelope
+
+Returns `{ data, total?, page?, pageSize?, totals? }` — see
+[[@concept-query-envelope]].
+
+## Related concepts
+
+- [[@concept-api-endpoints-overview]]
+- [[@concept-api-endpoint-properties]]
+- [[@concept-api-param-properties]]
+- [[@concept-api-scope-filter]]
+- [[@concept-query-envelope]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Endpoints → Query endpoint`