@supacloud/compiler 0.21.1 → 0.23.0

package/README.md

@@ -1,5 +1,43 @@
 # @supacloud/compiler
 
+## Unified Database Contracts
+
+`supacloud-compiler database-contracts database-contracts.json` generates a shared
+type entry point while preserving PostgREST, Drizzle and GraphQL native types:
+
+```json
+{
+  "rootDir": ".",
+  "outDir": "generated",
+  "postgrestTypes": "database.types.ts",
+  "drizzleSchema": "db/schema.ts",
+  "role": "authenticated",
+  "graphql": {
+    "schema": "graphql/schema.graphql",
+    "documents": ["src/**/*.graphql"]
+  },
+  "migrations": ["migrations/001.sql"]
+}
+```
+
+Configuration paths are relative to the configuration directory; GraphQL document
+patterns are resolved under `rootDir`. Supply the official PostgREST `Database`
+snapshot and a role-scoped `pg_graphql` schema snapshot. The generated barrel
+exports `Database`, `QueryData`, Drizzle schema types and GraphQL contracts.
+Consumers need `@supabase/supabase-js` and their Drizzle dependencies.
+
+`--check` detects drift in supplied snapshots, local Drizzle imports, migration
+content/order and generated artifacts without writing. This is an offline check,
+not proof of live database parity or authorization. Refresh snapshots from the
+intended database and role before running it. Keep runtime decoders at untrusted
+boundaries; protocol result shapes are not interchangeable.
+
+Compiled DI requires constructor injection and generated scope factories.
+Property `inject()` and runtime injection-context APIs fail with `SC2012`.
+Production SQL scanning reports non-`unknown` Drizzle `sql<T>` as `SC6007` and
+dynamic `sql.raw` as `SC6008`. Prefer parameters and explicit result decoders.
+These rules do not replace PostgreSQL constraints, RLS or migration review.
+
 ## Local Delivery
 
 `supacloud-compiler plan --json` previews workload targets, dependency closures,
@@ -407,7 +445,7 @@ IDE 和 AI agent 做状态机漂移检查。
 - 含 request/job 级 provider 或 controller 的模块同时生成异步静态 `create<Name>RequestScope` / `create<Name>JobScope` 与 `destroy<Name>RequestScope(scope)` / `destroy<Name>JobScope(scope)`；factory 在构造中途失败时按编译期确定的逆创建顺序回滚已知 `onDestroy` 方法，不会运行时扫描或解析 Token。
 - `@Host()` 在 EnvironmentInjector 作用域中保留元数据但不改变解析，因为 SupaCloud 没有 Angular 元素注入器树；`@Self()` / `@SkipSelf()` 由静态 factory 按当前 scope 与模块可见性执行。
 - AOP 只支持静态边界：`ModuleOptions.aspects`、`RouteOptions.aspects`、`CommandOptions.aspects` 和 `JobOptions.aspects` 必须是显式数组字面量，元素必须是可解析的函数标识符。生成器会直接 import aspect 并生成固定顺序的 onion chain，不使用 Proxy、Reflect 扫描、动态 pointcut 或运行时注册。
-- 执行顺序为 `module -> route -> command -> commandGovernance -> handler`；Job 使用 `module -> job -> executor -> run/execute`，并在 finally 中销毁 job scope。
+- 执行顺序为 `commandGovernance -> module -> route -> command -> handler`，授权拒绝不会运行业务切面；Job 使用 `module -> job -> executor -> run/execute`，并在 finally 中销毁 job scope。
 - services 对象的 key 为 token 名的 camelCase：`CaseService → caseService`、`CASE_REPOSITORY → caseRepository`、`LOGGER → logger`。
 - controller 描述静态给出：`{ path, serviceKey, scope, routes: [{ method, path, handler, body?, params?, query?, headers?, cookie?, response?, responses? }] }`，schema 直接引用 import 进来的对象。
 - `client.ts` 在启用 `generateClient` 时生成：包含 `API_ROUTES`、`API_SCHEMAS`、类型化请求选项和显式响应 decoder 入口。