@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-native/CAPABILITIES.md

@@ -0,0 +1,536 @@
+# Driver evidence and limitations
+
+<!-- Generated by buddy docs:native-skills from capabilityRegistry. -->
+
+The registry distinguishes supported, partial, experimental, and unsupported
+drivers. Unknown and unsupported selections fail. Partial and experimental
+drivers remain subject to the limitations below. Read prerequisites before
+deploying; a configuration type does not establish an implemented transport.
+
+## database: sqlite
+
+Status: **supported**. Topology: embedded.
+
+Implementation: [storage/framework/core/database/src/drivers/sqlite.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/sqlite.ts).
+
+Prerequisites:
+
+- Bun SQLite
+
+Retained evidence:
+
+- [storage/framework/core/database/tests/integration.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/integration.test.ts)
+- [storage/framework/core/database/tests/sqlite-tx-serialization.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/sqlite-tx-serialization.test.ts)
+
+## database: mysql
+
+Status: **supported**. Topology: client-server.
+
+Implementation: [storage/framework/core/database/src/drivers/mysql.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/mysql.ts).
+
+Prerequisites:
+
+- MySQL 26.7 service
+
+Limitations:
+
+- The migration files shipped under database/migrations are emitted for a single dialect (SQLite in the default template) and do not replay on MySQL. Regenerate them against MySQL (`buddy generate:migrations`) before migrating.
+
+Retained evidence:
+
+- [storage/framework/core/database/tests/integration.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/integration.test.ts)
+- [storage/framework/core/database/tests/affected-rows.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/affected-rows.test.ts)
+- [storage/framework/core/database/tests/ensure-database-sessions.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/ensure-database-sessions.test.ts)
+- [storage/framework/core/auth/tests/session-refresh-mysql.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/auth/tests/session-refresh-mysql.test.ts)
+
+## database: singlestore
+
+Status: **experimental**. Topology: client-server.
+
+Implementation: [storage/framework/core/database/src/drivers/mysql.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/mysql.ts).
+
+Prerequisites:
+
+- SingleStore service
+
+Limitations:
+
+- MySQL wire compatibility exists, but a dedicated conformance matrix is not published.
+
+## database: vitess
+
+Status: **experimental**. Topology: mysql-behind-vtgate.
+
+Implementation: [storage/framework/core/database/src/drivers/mysql.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/mysql.ts).
+
+Prerequisites:
+
+- A Vitess cluster reachable at vtgate
+
+Limitations:
+
+- No live cluster in CI; the retained evidence covers unsharded and sharded DDL profiles plus VSchema generation, not a round trip through vtgate.
+- Set DB_VITESS_SHARDED=true for a sharded keyspace; those keyspaces reject cross-shard foreign keys and AUTO_INCREMENT, so use application-generated IDs and a VSchema.
+- Schema changes on sharded keyspaces should go through Vitess online DDL.
+- A transaction spanning shards is best-effort or two-phase, not the single-node ACID the ORM assumes.
+
+Retained evidence:
+
+- [storage/framework/core/database/tests/vitess-constraints.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/vitess-constraints.test.ts)
+
+## database: postgres
+
+Status: **supported**. Topology: client-server.
+
+Implementation: [storage/framework/core/database/src/drivers/postgres.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/postgres.ts).
+
+Prerequisites:
+
+- PostgreSQL 17 service
+
+Limitations:
+
+- The migration files shipped under database/migrations are emitted for a single dialect (SQLite in the default template) and do not replay on PostgreSQL. Regenerate them against PostgreSQL (`buddy generate:migrations`) before migrating.
+
+Retained evidence:
+
+- [storage/framework/core/database/tests/postgres-pivot-timestamptz.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/postgres-pivot-timestamptz.test.ts)
+- [storage/framework/core/database/tests/postgres-transaction-scope.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/postgres-transaction-scope.test.ts)
+- [storage/framework/core/database/tests/affected-rows.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/affected-rows.test.ts)
+- [storage/framework/core/database/tests/ensure-database-sessions.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/ensure-database-sessions.test.ts)
+
+## database: turso
+
+Status: **experimental**. Topology: managed-service.
+
+Implementation: [storage/framework/core/database/src/dialect.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/dialect.ts).
+
+Prerequisites:
+
+- A Turso database (TURSO_DATABASE_URL, TURSO_AUTH_TOKEN), or a local libSQL server from `turso dev` / sqld
+
+Limitations:
+
+- Proven against a local sqld 0.24.32 (turso CLI 1.0.33 `turso dev`), not a hosted Turso database, and no libSQL service runs in CI yet, so the retained evidence skips its live half there.
+- SQLite SQL over Hrana HTTP: each statement outside a transaction is one request, and a transaction holds one server stream for its duration.
+- sqld refuses VACUUM, ATTACH, temporary tables and every PRAGMA except the read-only ones and foreign_keys.
+- Embedded replicas are not supported; the connection is always remote.
+- Inside transaction(), write through the tx handle: model writes use their own connection, as on PostgreSQL and MySQL, and wait while the transaction holds the write lock.
+- Scheduler onOneServer() locks stay per-host, as they are on SQLite.
+- `buddy db:backup` does not dump a Turso database; rely on Turso's own point-in-time restore.
+
+Retained evidence:
+
+- [storage/framework/core/database/tests/turso.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/tests/turso.test.ts)
+
+## database: dynamodb
+
+Status: **unsupported**. Topology: managed-service.
+
+Implementation: [storage/framework/core/database/src/drivers/dynamodb.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/database/src/drivers/dynamodb.ts).
+
+Prerequisites:
+
+- DynamoDB
+
+Limitations:
+
+- DynamoDB helpers are not an ORM SQL driver and cannot be selected as database.default.
+
+## queue: sync
+
+Status: **supported**. Topology: inline.
+
+Implementation: [storage/framework/core/queue/src/job.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/src/job.ts).
+
+Limitations:
+
+- Not durable.
+
+Retained evidence:
+
+- [storage/framework/core/queue/tests/jobs.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/tests/jobs.test.ts)
+
+## queue: database
+
+Status: **supported**. Topology: worker-and-embedded-sqlite.
+
+Implementation: [storage/framework/core/queue/src/job.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/src/job.ts).
+
+Prerequisites:
+
+- Bun SQLite for the retained CI contract
+
+Limitations:
+
+- Other SQL providers require their own provider evidence.
+
+Retained evidence:
+
+- [storage/framework/core/queue/tests/integration.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/tests/integration.test.ts)
+- [storage/framework/core/queue/tests/failure-path-correctness.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/tests/failure-path-correctness.test.ts)
+
+## queue: redis
+
+Status: **supported**. Topology: worker-and-redis.
+
+Implementation: [storage/framework/core/queue/src/drivers/redis.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/src/drivers/redis.ts).
+
+Prerequisites:
+
+- Redis 8.8 service
+
+Limitations:
+
+- The retained contract covers queue persistence operations; horizontal scaling and distributed-lock extensions require separate evidence.
+
+Retained evidence:
+
+- [storage/framework/core/queue/tests/redis-contract.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/queue/tests/redis-contract.test.ts)
+
+## queue: sqs
+
+Status: **unsupported**. Topology: managed-service.
+
+Prerequisites:
+
+- AWS SQS
+
+Limitations:
+
+- Configuration shape is reserved; dispatch fails loudly.
+
+## queue: memory
+
+Status: **unsupported**. Topology: in-process.
+
+Limitations:
+
+- Reserved driver name; dispatch fails loudly.
+
+## queue: beanstalkd
+
+Status: **unsupported**. Topology: client-server.
+
+Prerequisites:
+
+- Beanstalkd service
+
+Limitations:
+
+- Reserved driver name; dispatch fails loudly.
+
+## cache: memory
+
+Status: **supported**. Topology: in-process.
+
+Implementation: [storage/framework/core/cache/src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/src/drivers/index.ts).
+
+Limitations:
+
+- Not shared across processes.
+
+Retained evidence:
+
+- [storage/framework/core/cache/tests/Memory.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/tests/Memory.test.ts)
+- [storage/framework/core/cache/tests/ttl.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/tests/ttl.test.ts)
+
+## cache: redis
+
+Status: **supported**. Topology: client-server.
+
+Implementation: [storage/framework/core/cache/src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/src/drivers/index.ts).
+
+Prerequisites:
+
+- Redis 8.8 service
+
+Limitations:
+
+- The retained contract covers core cache and TTL operations; TLS/authenticated deployments require separate provider evidence.
+
+Retained evidence:
+
+- [storage/framework/core/cache/tests/redis-contract.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/tests/redis-contract.test.ts)
+
+## cache: singlestore
+
+Status: **experimental**. Topology: client-server.
+
+Implementation: [storage/framework/core/cache/src/drivers/singlestore.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/cache/src/drivers/singlestore.ts).
+
+Prerequisites:
+
+- SingleStore service
+
+Limitations:
+
+- No dedicated CI service matrix.
+
+## storage: local
+
+Status: **supported**. Topology: local-filesystem.
+
+Implementation: [storage/framework/core/storage/src/adapters/local.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/adapters/local.ts).
+
+Retained evidence:
+
+- [storage/framework/core/storage/tests/localStorage.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/localStorage.test.ts)
+- [storage/framework/core/storage/tests/deep-integration.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/deep-integration.test.ts)
+
+## storage: memory
+
+Status: **supported**. Topology: in-process.
+
+Implementation: [storage/framework/core/storage/src/adapters/memory.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/adapters/memory.ts).
+
+Limitations:
+
+- Not persistent.
+
+Retained evidence:
+
+- [storage/framework/core/storage/tests/memoryAdapter.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/memoryAdapter.test.ts)
+
+## storage: s3
+
+Status: **partial**. Topology: managed-object-storage.
+
+Implementation: [storage/framework/core/storage/src/adapters/s3.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/adapters/s3.ts).
+
+Prerequisites:
+
+- S3-compatible service and credentials
+
+Limitations:
+
+- CI covers request construction but not a live provider round trip.
+
+Retained evidence:
+
+- [storage/framework/core/storage/tests/s3-presigned-post.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/s3-presigned-post.test.ts)
+
+## storage: bun
+
+Status: **partial**. Topology: local-filesystem.
+
+Implementation: [storage/framework/core/storage/src/adapters/bun.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/adapters/bun.ts).
+
+Prerequisites:
+
+- Bun runtime
+
+Limitations:
+
+- Adapter-specific feature parity is not fully reported.
+
+Retained evidence:
+
+- [storage/framework/core/storage/tests/bunAdapter.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/bunAdapter.test.ts)
+
+## storage: azure
+
+Status: **partial**. Topology: managed-object-storage.
+
+Implementation: [storage/framework/core/storage/src/adapters/azure.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/src/adapters/azure.ts).
+
+Prerequisites:
+
+- An Azure storage account, a container, and an account key or SAS token
+
+Limitations:
+
+- CI covers Shared Key and service-SAS signing plus request construction, not a live container round trip.
+- Visibility is a container property on Azure, so changeVisibility() refuses rather than silently doing nothing; a per-object grant is signedUrl().
+- ensureConfiguredBuckets provisions S3 buckets only, so the container must exist before the disk is used.
+
+Retained evidence:
+
+- [storage/framework/core/storage/tests/azure-adapter.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/azure-adapter.test.ts)
+- [storage/framework/core/storage/tests/azure-signing.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/storage/tests/azure-signing.test.ts)
+
+## mail: log
+
+Status: **supported**. Topology: local-file.
+
+Implementation: [storage/framework/core/email/src/drivers/log.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/log.ts).
+
+Limitations:
+
+- Development/testing transport only.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/email.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/email.test.ts)
+
+## mail: capture
+
+Status: **supported**. Topology: in-process.
+
+Implementation: [storage/framework/core/email/src/drivers/capture.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/capture.ts).
+
+Limitations:
+
+- Testing transport only.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/email.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/email.test.ts)
+
+## mail: smtp
+
+Status: **partial**. Topology: smtp-server.
+
+Implementation: [storage/framework/core/email/src/drivers/smtp.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/smtp.ts).
+
+Prerequisites:
+
+- smtp credentials
+
+Limitations:
+
+- CI validates configuration and request behavior without a live delivery assertion.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/driver-credentials.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/driver-credentials.test.ts)
+
+## mail: ses
+
+Status: **partial**. Topology: managed-service.
+
+Implementation: [storage/framework/core/email/src/drivers/ses.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/ses.ts).
+
+Prerequisites:
+
+- ses credentials
+
+Limitations:
+
+- CI validates configuration and request behavior without a live delivery assertion.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/driver-credentials.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/driver-credentials.test.ts)
+
+## mail: sendgrid
+
+Status: **partial**. Topology: managed-service.
+
+Implementation: [storage/framework/core/email/src/drivers/sendgrid.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/sendgrid.ts).
+
+Prerequisites:
+
+- sendgrid credentials
+
+Limitations:
+
+- CI validates configuration and request behavior without a live delivery assertion.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/driver-credentials.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/driver-credentials.test.ts)
+
+## mail: mailgun
+
+Status: **partial**. Topology: managed-service.
+
+Implementation: [storage/framework/core/email/src/drivers/mailgun.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/mailgun.ts).
+
+Prerequisites:
+
+- mailgun credentials
+
+Limitations:
+
+- CI validates configuration and request behavior without a live delivery assertion.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/driver-credentials.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/driver-credentials.test.ts)
+
+## mail: mailtrap
+
+Status: **partial**. Topology: managed-service.
+
+Implementation: [storage/framework/core/email/src/drivers/mailtrap.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/src/drivers/mailtrap.ts).
+
+Prerequisites:
+
+- mailtrap credentials
+
+Limitations:
+
+- CI validates configuration and request behavior without a live delivery assertion.
+
+Retained evidence:
+
+- [storage/framework/core/email/tests/driver-credentials.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/email/tests/driver-credentials.test.ts)
+
+## realtime: websocket
+
+Status: **supported**. Topology: single-process-websocket.
+
+Implementation: [storage/framework/core/realtime/src/server-instance.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/realtime/src/server-instance.ts).
+
+Prerequisites:
+
+- Bun server
+
+Limitations:
+
+- Scale-out requires an application-provided fan-out layer.
+
+Retained evidence:
+
+- [storage/framework/core/realtime/tests/ws-auth.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/realtime/tests/ws-auth.test.ts)
+- [storage/framework/core/realtime/tests/websocket-options.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/realtime/tests/websocket-options.test.ts)
+
+## deploy: ts-cloud-hetzner
+
+Status: **experimental**. Topology: hetzner-vm-systemd-rpx.
+
+Implementation: [storage/framework/core/buddy/src/commands/deploy.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/commands/deploy.ts).
+
+Prerequisites:
+
+- @stacksjs/ts-cloud
+- Hetzner credentials
+- SSH key
+
+Limitations:
+
+- Live provider evidence and rollback conformance are not yet retained in the protocol report.
+
+Retained evidence:
+
+- [storage/framework/core/buddy/tests/deploy-ssh-target.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/tests/deploy-ssh-target.test.ts)
+
+## deploy: ts-cloud-ssh
+
+Status: **experimental**. Topology: ssh-box-systemd-rpx.
+
+Implementation: [storage/framework/core/buddy/src/commands/deploy-ssh-target.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/src/commands/deploy-ssh-target.ts).
+
+Prerequisites:
+
+- @stacksjs/ts-cloud with the ssh driver
+- A 64-bit Debian or Ubuntu host reachable over SSH
+- Passwordless sudo when deploying as a non-root user
+
+Limitations:
+
+- DNS, TLS issuance, CDN and mail reconciliation are skipped for a host on a private address.
+- One app host per project; multi-host ssh fleets are not supported.
+- No live hardware evidence is retained in CI.
+
+Retained evidence:
+
+- [storage/framework/core/buddy/tests/deploy-ssh-target.test.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/buddy/tests/deploy-ssh-target.test.ts)
+
+## Optional application bundles
+
+Installable bundle names: `dashboard`, `commerce`, `cms`, `forms`, `marketing`, `monitoring`, `realtime`, `queue`.
+
+Read `stacks-features` for installation, config gates, route bundles, and
+migration selection. These are distinct from user-targeted feature flags.