Implementation status

Implementation Status

Release classification required by framwork.md §10. Validated means covered by an automated test that passes in bun run test; implemented means working and exercised manually but without a dedicated automated test; planned means specified but not built (the CLI lists it and exits with code 3).

Last verified: 2026-10-27 — bun run test all green (427 tests incl. the scaffold-generator gate, validation/testing package suites and deepened scheduler/events/ai-mcp coverage), bun run coverage gate green (per-package line/function thresholds), bun run typecheck clean, bun run lint clean.

Delivery phases

Phase	Deliverable	Status	Gate evidence
0	Runtime/adapter decisions, pinned dependencies	Done	decisions.md compatibility matrix
1	Core lifecycle, config, request scope, HTTP errors	Done	packages/core/tests, packages/http/tests (concurrent scope isolation, partial-boot cleanup, disposal)
2	One coherent CRUD module with schemas/policy/OpenAPI	Done	apps/playground products suite on real PostgreSQL, tests/contract.test.ts (OpenAPI drift + typed RPC client), migration 0000_create-products.sql
3	Sessions/tokens/recovery/OTP/policies	Done	Sessions/tokens/policies, email verification, password recovery, TOTP two-step login, JWT/JWK guard and ownership policies — all validated on real PostgreSQL (packages/auth/tests: account-security.test.ts end-to-end flows, jwt-guard.test.ts with remote-JWKS rotation, routes.test.ts/rate-limit.test.ts HTTP gates)
4	Cache/queue/storage/mail/events/scheduling	Done	Events (packages/events: in-memory + Redis pub/sub, WebSocket hub), queue (packages/queue: dispatch/worker/batches over QueueKit’s BullMQ provider, retries, timeouts), scheduling (packages/scheduler) and workflows (packages/workflow) — all validated; cache (packages/cache: memory/Redis over CacheKit, locks, fixed-window rate limiting), storage (packages/storage: disks over StorageKit with multi-driver config), mail (packages/mail), notifications (packages/notifications: explicit channels, queued delivery, per-channel status) and logging (packages/logging: LoggerKit sinks with ambient correlation + redaction) — each validated against real infrastructure
5	CLI inventory and generators	Substantial	make:crud and create validated end to end; make:job/make:seeder/make:factory validated (generate → typecheck → register); the 20 scaffold generators (make:schema/repository/dto/request/response/service/controller/policy + make:middleware/provider/event/listener/test + make:mail/notification/command/schedule/guard/user-provider/migration) validated as a batch (dry-run byte-neutrality, conflict refusal, marker registration visible to runtime commands, one typecheck — packages/cli/tests/generators.test.ts); queue management, db:seed/db:fresh and build validated against real infrastructure (packages/cli/tests/lifecycle.test.ts); only make:model/make:integration stay planned
6	Release documentation and deployment	Substantial	Local Postgres/Redis compose, server + worker entry points with graceful shutdown; generated apps ship a multi-stage Bun Dockerfile, compose server/worker services with healthchecks, and /health/ready probing database + Redis + queue; Starlight docs site (apps/docs, MDX + Cloudflare adapter) building and deployable via wrangler

Packages

Package	Status	Notes
@framework/core	Validated	Container (singleton/scoped/transient, cycle + captive-dependency detection), providers (ordering, deferred, partial-boot cleanup), validated frozen config, redaction, graceful shutdown, ExecutionContext (default scope binding; overridden per request/job with real ids/actors)
@framework/http	Validated	Kernel (request id → body limit → request scope → strict security headers → CORS), onError envelope, middleware alias/group registry, duplicate-route detection (incl. the same handler mounted twice back to back), route listing, resource policies, principal plumbing (PrincipalLike context var, requireAuth → 401, authenticatedPolicy, hasAbility), mount-time authorization for guardable route families (authorizationGuard, MountAuthorization), generic throttle middleware over a structural limiter contract (429 + Retry-After, per-request limiter resolvers)
@framework/auth	Validated	Session + personal API token authentication: argon2id password hashing, framework-owned users/sessions/api_tokens/account_tokens/totp_recovery_codes tables, DB-backed session store (sha256 at rest, rotation on login, sliding expiry, prune) and token store (hash at rest, abilities, expiry, revocation, ownership checks), DatabaseUserProvider (+ swappable UserProvider contract), AuthService (register/startLogin (two-step fork)/completeTwoStep/attempt/startSession/issueToken/logout/revoke-all), email verification (single-use hashed tokens, verified() middleware), password recovery (no enumeration, constant-time verification, full credential rotation on reset), two-step TOTP login (RFC 6238 over node:crypto, ±1-step window, one-time recovery codes, challenge consumed up front), JWT/JWK guard over jose (RS/ES/PS/EdDSA, remote JWKS with kid rotation, iss/aud checks, scope/abilities claims, sub → local user), guard wired via the kernel’s resolveActor (auth.guards order), requireAbility/verified middleware, /auth endpoints (register/login/two-step/logout/me, email verification, password reset, TOTP enrollment, token issue/list/revoke; CSRF on cookie flows via native Hono csrf), createAuthProvider + authActorResolver composition helpers, OpenAPI operations in the playground
@framework/validation	Validated	validate() (zod-validator, 422 field errors, RPC-preserving types), form requests with authorization hooks — direct suite in packages/validation/tests (envelope shape, field-path rendering, 403-before-422 ordering, async hooks)
@framework/database	Validated	postgres-js connection, AsyncLocalStorage transactions with savepoints, CRUD mixins incl. bulk operations (createMany, updateMany, deleteMany, deleteByIds, restoreMany — audited per record), findMany/count/exists, DataContext (transactions + execution context), audit trail (audit_logs, Auditable mixin, AuditReader), bounded pagination, locked migrations + status, Drizzle–Zod adapter, ISO timestamp helper
@framework/crud	Validated	Generic CRUD layer over the database mixins: ResourceService base (shared ServiceContext — actor + transaction chain — injected per scope, lifecycle hooks, transaction() orchestration, entity events, not-found translation, row-level ownership via ownedBy(field) — queries scoped to the acting user, cross-owner reads/writes are 404, writes stamp the owner, owner-less scopes see nothing), ResourceController base (typed handlers + serialization), auditRoutes + importExportRoutes (mount-time authorization required: guard callback, auth middleware, or explicit 'public'; guards run before validation), resourceOperations + dataOperations (OpenAPI operations derived from the controller contract and the import/export routes), CSV codec, queued import/export jobs (defineImportJob/defineExportJob, partial-success batches, progress events, LocalExportStore and DiskExportStore over any storage disk for multi-node), DataPorter (mounted and OpenAPI-documented in the playground and generated apps). Generated services/controllers extend these bases with default wiring users can override
@framework/events	Validated	EventBus contract, in-memory bus, Redis pub/sub (namespaced, validated payloads, dedicated subscriber connection), RealtimeHub + native WebSocket routes (channel allowlist, per-connection authorization, subscription limits)
@framework/queue	Validated	Enqueue and provider lifecycle routed through @mohamedhabibwork/queuekit’s BullMQ provider behind an internal adapter seam; inspection/retry/pause and worker creation stay on the direct BullMQ handle (documented queuekit 0.4.1 gaps). QueueManager (payload validation before enqueue, idempotency keys, delayed dispatch, status/failed/retry/retry-all/forget/prune/counts/pause/resume) and JobWorker (per-job scopes with the dispatcher’s execution context, timeouts, graceful drain). Batches: dispatchBatch fans out validated payloads under one id with Redis bookkeeping (atomic HINCRBY counters + HSETNX finish claim), batchStatus/batchFailures/cancelBatch, and an optional completion job fired when the batch settles
@framework/cache	Validated	Storage engines delegate to @mohamedhabibwork/cachekit (memory provider; Redis via createRedisCompatibleCache driven by Bun’s native RedisClient — no redis peer needed). Cache (get/set/has/remember/delete, atomic fixed-window counters, TTL), LockStore (Redis SET NX PX + owner-token release via the engine’s native command surface; memory equivalent), RateLimiter (fixed window, failures-only reset support), capability flags mapped from the engine’s matrix (Redis: distributed locks native; tags/clearNamespace reported unsupported rather than faked), JSON pre-validation before writes, createCacheProvider (config driver: 'memory' | 'redis'), namespaced keys, never flushes shared Redis
@framework/storage	Validated	File operations delegate to @mohamedhabibwork/storagekit (local provider; kit errors mapped onto the framework catalog). StorageDisk contract: put/get/stream/delete/exists/size/list(bounded)/move/copy, private/public visibility with separate roots (public URL impossible on private disks), path guard as defense-in-depth in front of the kit (14 traversal attempts rejected), upload size/extension guard, temp pruning with pruneTemp, capability honesty (local signedUrl unsupported). Config: driver: 'local' validated strictly; s3/r2/minio/azure/gcs/oracle/rustfs pass-through drivers fail boot with STORAGE_DRIVER_UNAVAILABLE until their peer SDK is installed
@framework/mail	Validated	Zod-validated MailMessage (text-or-html refine, normalized recipients), MailTransport contract with capability flags, ConsoleMailTransport (bodies redacted to byte counts in logs), MemoryMailTransport as the documented test fake with one-shot failure injection, Mailer builder applying the default from, createMailProvider. SMTP deferred with a documented plan (SMTP_PLANNED); queue hand-off documented as an @framework/queue integration point
@framework/notifications	Validated	Explicit channel selection (email via the bound Mailer, database via an app-owned DatabaseChannelStore that doubles as the delivery-status ledger; sms documented planned). NotificationsService.send (inline fan-out with per-channel status and failure isolation) and sendQueued (versioned, idempotent defineNotificationJob over @framework/queue — retries ride the queue; delivered channels never re-sent on resume), defineNotification fail-fast definitions, createNotificationsProvider
@framework/logging	Validated	FrameworkLogger wraps @mohamedhabibwork/loggerkit: console/file/memory sinks via validated config, every entry enriched with the ambient execution context (correlation id, actor), fields redacted through core’s redact (one redaction truth shared with support’s logger), child() inheritance, flush/close via provider dispose; bindLogger adapts arbitrary loggerkit instances

Kit-backed subsystems end to end

All five @mohamedhabibwork kits are adapted behind framework contracts (ADR-11) and wired through the whole stack: the playground binds cache/logging/storage providers and implements the CLI runtime hooks (cache, sessions), so cache:clear, storage:check and session:prune execute for real (bun run cli -- cache:clear --dry-run); generated apps ship the same providers, config sections (env-mapped) and hooks from create, with the sessions hook tolerating apps that have not run make:auth yet. Notifications gains push (fcm/apns/webpush/huawei) and messaging (telegram/slack) channels over NotifyKit with per-channel provider config; email stays on @framework/mail by design. Gate evidence: packages/cli/tests/create-app.test.ts (kit assertions in the generated-app gate), packages/cli/tests/cli.test.ts (provider gates + playground end-to-end), packages/notifications/tests/notifications-kit.test.ts (27 package tests). | @framework/workflow | Validated | Durable Workflow → Pipeline → Stage → Action engine over Postgres (workflow_runs + workflow_nodes execution tree, conditional transitions) with BullMQ as transport: defineWorkflow/definePipeline/defineStage/defineAction + parallel() groups, via: 'inline' \| 'queue' execution placement, stage/action precheck gates and when conditions, per-action retries/timeouts, reverse-order saga compensation, wait-for-event stages (event-bus bridge + timeout sweep), cancel/retry/resume/prune, workflowRoutes() admin API, progress events on workflow / workflow.run.<id> channels | | @framework/scheduler | Validated | defineSchedule (cron + timezone + skip/replace overlap) onto BullMQ job schedulers; fires run on a dedicated -schedules queue consumed by the scheduler process and dispatch jobs or workflows with a Redis overlap lock and schedule:{name}:{fireId} idempotency | | @framework/openapi | Validated | OpenAPI 3.1 from operation metadata + Zod (z.toJSONSchema), route/operation drift check, per-status ErrorEnvelope<status> components with catalogued code enums (422 additionally carries the fields schema) | | @framework/testing | Validated | Isolated per-run PostgreSQL databases (always dropped), production-target guards, ephemeral loopback server — self-tested in packages/testing/tests (missing-URL contract, create/drop idempotence, production and application-URL guards, migration application, cleanup on failure) | | @framework/ai-mcp | Implemented | stdio MCP server bridging the application CLI in-process (embeddable runCli, forced --json --no-interaction, serialized invocations, long-running command rejection, whitelisted docs tools + fwdocs:// resources); suite in packages/ai-mcp/tests (command admission, argument validation, banned-flag stripping, envelope fallbacks, docs clamping, published schemas). Known limitation: a timed-out invocation cannot be cancelled in-process, so the serialized queue stays busy until it settles | | @framework/support | Validated | Laravel-style helpers: config()/env() (runtime config + process env), abort()/abort_if()/abort_unless() (catalogued HTTP errors), logger() (JSON lines bound to the current correlation id/actor), correlationId()/currentActor()/execution() (ambient scope via AsyncLocalStorage, wired into the HTTP kernel and job worker), retry(), sleep(), tap(), value(), uuid(), nowIso(), redactForLogs() | | @framework/cli | Validated (subset) | See command table |

CLI commands

Command	Status
create	Validated — full app startup generator (packages/cli/tests/create-app.test.ts): generates a workspace-member application (config, bootstrap, providers incl. events/queue/audit, health + audit + realtime routes, server/worker/CLI bins, tests, compose, drizzle config); generated app typechecks, passes its suite, migrates audit_logs, and accepts make:crud --verify. --with-demo additionally runs make:crud inside the new app (same pipeline, no duplication) to ship a sample products module with migration; the one-command path is gate-tested including its endpoint suite
make:crud	Validated — new table (+ --soft-delete), existing table with integer key, --access public|authenticated (authenticated policies map CRUD abilities to <resource>.<ability> token abilities; generated suites include 401/403 cases; requires the auth module), --test-mode network, conflict and route-collision refusal, generated app’s full suite (packages/cli/tests/generated-app.test.ts), and inside create-generated apps
make:auth	Validated — Phase 3 gate (packages/cli/tests/auth-app.test.ts): installs app/modules/auth (provider + routes), registers the dependency (@framework/auth + bun install), wires config/schema/provider/kernel-guard/route-mount edits, and generates the users/sessions/api_tokens migration; --guards session,api-token, --dry-run, refuses when already installed
make:module --crud	Implemented (delegates to the same pipeline)
queue:work, queue:status	queue:work implemented (foreground worker, SIGTERM/SIGINT drain — exercised manually); queue:status validated against real Redis
queue:failed, queue:retry, queue:retry-all, queue:forget, queue:prune, queue:pause, queue:resume	Validated against real Redis (packages/cli/tests/lifecycle.test.ts: pause/resume flip, failed listing, catalogued refusal for unknown ids); the manager surface rides the direct BullMQ handle
db:seed	Validated end to end (defineSeeder/defineFactory in @framework/database, shared with tests; playground registers a real products seeder via the seeders CLI hook): runs all or one-by-name, idempotent, catalogued errors for missing hook/unknown name
db:fresh	Validated end to end: drops public + the drizzle journal schema and re-runs the full migration journal; refuses production targets without --force
build	Validated: bun build --compile --minify --sourcemap per entry point into dist/, optional storage/notifications peer SDKs kept external
make:job, make:seeder, make:factory	Validated (generate → typecheck → registry visible to db:seed): shared plan/conflict/--dry-run/--force pipeline from make:crud; registries updated via markers
make:schema, make:repository, make:dto, make:request, make:response, make:service, make:controller, make:policy, make:middleware, make:provider, make:event, make:listener, make:test	Validated as a batch (packages/cli/tests/generators.test.ts): dry-run byte-neutrality, conflict refusal (exit 2 without --force), marker registration visible to module:list/middleware:list/db:generate, and one tsc pass over all generated code. The eight resource slices render through the make:crud pipeline (byte-identical output; module-coupled slices require their referenced artifacts and say which command creates them). make:listener registers into the app/listeners registry that the generated listenersProvider consumes at boot
help, list, --json envelope, exit codes 0/2/3, --dry-run writes nothing	Validated (packages/cli/tests/cli.test.ts)
db:generate, openapi:check	Validated (end-to-end test)
db:migrate, db:status, db:check, db:fresh, db:seed, config:check, config:show, doctor, route:list, module:list, middleware:list, openapi:generate, serve, dev, typecheck, test, lint, format, build	Implemented (db:fresh, db:seed and build additionally validated against real infrastructure)
workflow:list, workflow:status, workflow:retry, workflow:cancel, workflow:prune	Validated against real PostgreSQL (packages/workflow/tests); exercised manually against the playground demo
schedule:list, schedule:run, schedule:test, schedule:work	Validated against real Redis (packages/scheduler/tests); schedule:test verified end-to-end (fire → scheduler process → workflow run on the worker)
cache:clear, storage:check, session:prune	Validated — provider-gated (unregistered provider → exit 3 with an actionable hint); cache:clear and session:prune require --confirm (dry-run supported; prune dry-run counts via countExpired without deleting); runtime execution goes through optional project-adapter hooks (cache/sessions), consistent with queue:work’s worker hook
make:mail, make:notification, make:command, make:schedule, make:guard, make:user-provider, make:migration	Validated as a batch in the same gate (packages/cli/tests/generators.test.ts): dry-run byte-neutrality, conflict refusal, input validation (channels, cron, signature, header, migration name, missing job), registration into app/schedules / app/commands (+ bin/cli.ts wiring), the generated app:* command executing through the project CLI, make:migration landing in the Drizzle journal, and one tsc pass over all generated code. Package-importing generators refuse when the app lacks the dependency
integration:*, remaining make:* (model, integration), db:rollback, remaining storage:*, cache:prune	Planned (exit 3). make:model stays out of scope with the ORM layer. db:rollback documents the forward-only migration decision — reset non-production targets with db:fresh, author a new forward migration to revert a change

Run bun run cli -- list for the live catalog.

Generated application (create)

bun run cli -- create apps/<name> generates the complete application skeleton the release gate exercises: validated config (app/http/database/redis/queue/events), database + events providers, audit_logs in the canonical schema, /health + /audit + /ws (WebSocket event multiplexing) routes, bin/server.ts + bin/worker.ts + bin/cli.ts entry points, a health smoke suite, deployment compose, drizzle config, and a README. make:crud --verify then adds a full resource module. Generated apps are framework-workspace members: dependencies resolve through workspace:* after a root bun install (the create command runs it unless --no-install).

Known limitations

• Generated CRUD supports a single primary key named id (uuid for new tables; uuid/integer/serial for existing tables). Unique/foreign-key fixtures, relations, enums and JSON columns are rejected rather than guessed.
• Generated resources support --access public and (after make:auth) --access authenticated; per-principal ownership is available as a service-level ownedBy('userId') scope but is not yet a make:crud flag, and the ?include= relations DSL is not generated.
• Import/export covers CSV and JSON (streaming keyset batches, queued, partial-success imports). XLSX/PDF formats are planned. Export artifacts can live on any storage disk (DiskExportStore) or local disk (LocalExportStore).
• TOTP two-step login provisions the RFC 6238 §5 SHA-256 variant only (algorithm=SHA256); the weak-digest legacy variant is intentionally not offered, so authenticator apps without SHA-256 support (notably Google Authenticator) cannot enroll — modern apps (Aegis, 1Password, Bitwarden, FreeOTP, Ente Auth) work. Documented in packages/auth/src/totp.ts.
• TOTP secrets are stored in the users table unencrypted (standard practice — they must be retrievable to verify codes); database-at-rest encryption is a deployment concern.
• Node runtime is not selectable; only Bun is validated (the generated Dockerfile pins oven/bun:1.4.2). Promoting Node to a supported runtime still needs the ADR the enhancement plan called for.
• Batch bookkeeping (queue batches) lives in Redis with a TTL, so batch history is bounded by design; durable fan-out with history belongs in workflows.
• OpenTelemetry tracing/metrics and the “every CLI command has a status.md row” CI check are planned (M7 remainder). Per-status OpenAPI error schemas ship today: every declared error status gets an ErrorEnvelope<status> component whose code is the exact catalog enum (from ERROR_CATALOG, now shared via @framework/core), and bun run coverage enforces per-package line/function thresholds (measured baselines; template files and test files excluded).
• SMTP transport, the SMS notification channel, and validated s3/r2/minio storage against MinIO in compose are planned (M6 remainder).
• Migrations are forward-only by decision: db:rollback stays planned with a pointer to db:fresh (non-production) and authoring a new forward migration.
• The docs site vendors MDX 8’s wasm32 runtime (apps/docs/vendor/, installed by a postinstall script) because bun skips wasm32 optional dependencies; astro dev renders through Node via the Cloudflare adapter’s prerenderEnvironment: 'node'.