@getstrata/core 3.0.4 → 3.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +17 -9
  3. package/dist/core/auth/policy.d.ts +4 -1
  4. package/dist/core/auth/saml/samlServiceProvider.d.ts +2 -3
  5. package/dist/core/cache/createCacheStore.d.ts +1 -1
  6. package/dist/core/cache/expiration.d.ts +2 -0
  7. package/dist/core/cache/redisCacheScript.d.ts +1 -1
  8. package/dist/core/cache/redisCacheStore.d.ts +5 -5
  9. package/dist/core/cache/repository.d.ts +2 -0
  10. package/dist/core/cache/simpleCache.d.ts +5 -5
  11. package/dist/core/cache/simpleCacheStore.d.ts +3 -3
  12. package/dist/core/cache/store.d.ts +5 -4
  13. package/dist/core/cache/taggedCache.d.ts +2 -0
  14. package/dist/core/cache/tokens.d.ts +1 -1
  15. package/dist/core/config/envSchema.d.ts +13 -0
  16. package/dist/core/contracts/application.d.ts +4 -0
  17. package/dist/core/contracts/di.d.ts +2 -2
  18. package/dist/core/contracts/provider.d.ts +13 -0
  19. package/dist/core/contracts/serviceTokens.d.ts +12 -11
  20. package/dist/core/database/factory.d.ts +3 -0
  21. package/dist/core/database/index.d.ts +1 -1
  22. package/dist/core/database/migrations/declaration.d.ts +11 -0
  23. package/dist/core/database/migrations/runner.d.ts +2 -0
  24. package/dist/core/database/model.d.ts +16 -3
  25. package/dist/core/database/modelQuery.d.ts +1 -10
  26. package/dist/core/database/modelRelationLoader.d.ts +31 -0
  27. package/dist/core/database/mysqlConnection.d.ts +2 -2
  28. package/dist/core/database/mysqlNative.d.ts +2 -0
  29. package/dist/core/database/ormRuntime.d.ts +1 -1
  30. package/dist/core/database/rawMysql.d.ts +1 -1
  31. package/dist/core/events/eventBusClass.d.ts +6 -3
  32. package/dist/core/events/index.d.ts +1 -1
  33. package/dist/core/http/formRequest.d.ts +2 -0
  34. package/dist/core/http/loginThrottleMiddleware.d.ts +1 -2
  35. package/dist/core/http/memoryThrottleMiddleware.d.ts +1 -3
  36. package/dist/core/http/webFormRequest.d.ts +3 -5
  37. package/dist/core/mail/mailer.d.ts +6 -3
  38. package/dist/core/mail/markdownMailable.d.ts +2 -2
  39. package/dist/core/notifications/dispatcher.d.ts +5 -5
  40. package/dist/core/notifications/index.d.ts +1 -1
  41. package/dist/core/notifications/types.d.ts +9 -2
  42. package/dist/core/queue/index.d.ts +8 -3
  43. package/dist/core/queue/queueHandoff.d.ts +2 -2
  44. package/dist/core/runtime/application.d.ts +2 -0
  45. package/dist/core/security/oauthState.d.ts +12 -2
  46. package/dist/core/security/safeUrl.d.ts +1 -11
  47. package/dist/core/storage/storage.d.ts +23 -6
  48. package/dist/core/testing.d.ts +5 -0
  49. package/dist/core/testingState.d.ts +22 -0
  50. package/dist/entries/audit/exportAuditLogs.js +1 -0
  51. package/dist/entries/auth/intendedUrlCookie.js +106 -18
  52. package/dist/entries/auth/jwt.js +68 -6
  53. package/dist/entries/auth/jwtGuard.js +76 -12
  54. package/dist/entries/auth/oauth/samlProvider.js +4 -5
  55. package/dist/entries/auth/passwordConfirmCookie.js +69 -3
  56. package/dist/entries/auth/saml/samlServiceProvider.js +5 -7
  57. package/dist/entries/auth/sessionCookie.js +69 -6
  58. package/dist/entries/auth/sessionGuard.js +69 -6
  59. package/dist/entries/cache/createCacheStore.js +45 -23
  60. package/dist/entries/cache/repository.js +20 -5
  61. package/dist/entries/cache/simpleCache.js +21 -7
  62. package/dist/entries/cache/simpleCacheStore.js +2 -3
  63. package/dist/entries/config/envSchema.js +13 -0
  64. package/dist/entries/contracts/serviceTokens.js +2 -0
  65. package/dist/entries/database/bindings.js +19 -95
  66. package/dist/entries/database/factory.js +4 -0
  67. package/dist/entries/database/migrations.js +714 -1
  68. package/dist/entries/database/ownedReadOnlyObservation.js +1 -5
  69. package/dist/entries/database/sqliteConnection.js +1 -5
  70. package/dist/entries/http/flashMiddleware.js +33 -14
  71. package/dist/entries/http/flashSession.js +33 -14
  72. package/dist/entries/http/formRequest.js +12 -6
  73. package/dist/entries/http/memoryThrottleMiddleware.js +12 -11
  74. package/dist/entries/http/pagination.js +4 -4
  75. package/dist/entries/http/parseMultipartUpload.js +62 -9
  76. package/dist/entries/http/requirePasswordConfirmMiddleware.js +5 -2
  77. package/dist/entries/http/requireWebAuthMiddleware.js +5 -2
  78. package/dist/entries/http/routeModelBinding.js +4 -4
  79. package/dist/entries/http/safeInternalPath.js +5 -2
  80. package/dist/entries/http/scimThrottleMiddleware.js +5 -2
  81. package/dist/entries/http/securedRouteModelBinding.js +4 -4
  82. package/dist/entries/http/throttleMiddleware.js +5 -2
  83. package/dist/entries/http/uploads.js +62 -9
  84. package/dist/entries/http/validation.js +4 -4
  85. package/dist/entries/http/webFormRequest.js +74 -95
  86. package/dist/entries/jobs/exportAuditLogsJob.js +9 -4
  87. package/dist/entries/jobs/invalidateCacheTagsJob.js +9 -4
  88. package/dist/entries/queue/createAppQueue.js +10 -5
  89. package/dist/entries/queue/publicQueue.js +10 -5
  90. package/dist/entries/queue/queueWorkerTransport.js +10 -5
  91. package/dist/entries/queue.js +9 -4
  92. package/dist/entries/runtime/application.js +50 -3
  93. package/dist/entries/security/oauthState.js +61 -2
  94. package/dist/entries/security/tokenExpiry.js +62 -9
  95. package/dist/entries/storage/storage.js +102 -1
  96. package/dist/entries/testing.js +18 -0
  97. package/dist/framework/public-api.d.ts +16 -13
  98. package/dist/index.js +380 -266
  99. package/dist/internal/mysqlNative.js +97 -0
  100. package/dist/internal/ormRuntime.js +41 -4
  101. package/dist/internal/testingState.js +31 -0
  102. package/dist/types/services.d.ts +8 -1
  103. package/package.json +17 -4
package/CHANGELOG.md CHANGED
@@ -1,5 +1,33 @@
1
1
  # @getstrata/core changelog
2
2
 
3
+ ## 3.0.7
4
+
5
+ Carry forward the 3.0.6 application-authoring and correctness changes after its release stopped before publication. Correct SAML release acceptance to require browser-bound state while preserving assertion validation, successful login and MFA. See docs/releases/3.0.7.md for upgrade notes.
6
+
7
+ ## 3.0.6
8
+
9
+ - Add concise `createModel` declarations and declarative `defineProvider` bindings with phased setup/boot, preserving explicit persistence ownership, observers and scopes.
10
+ - Add `defineMigration` authoring, Bun-backed local/S3 streaming storage, structural mail/storage ports and application-owned notification channels.
11
+ - Share form-request validation, parse bodies by Content-Type, require explicit authorization and reject malformed integer query parameters. Require atomic tagged-cache loading; preserve notification HTML and validate database notification IDs.
12
+ - Preserve exact oversized MySQL integers without changing safe numeric IDs. Keep `mysql2` as the qualified optional MySQL adapter; it remains lazily loaded.
13
+ - Prevent closed MySQL connections from reopening, drain admitted transactions through both SQL entrypoints, and seal raw MySQL/PostgreSQL pool admission while native cleanup is pending. Concurrent close shares one cleanup result.
14
+ - Drain synchronous and asynchronous production queue jobs, including jobs that initiate shutdown, while preserving dispatch failures. Fix immediate outbox worker start/stop admission races.
15
+ - Bind password-confirmation signatures to their purpose. Require matching browser state for OAuth callbacks and add dedicated secure SAML state-cookie helpers; OIDC retains its PKCE binding.
16
+ - Keep valid short JWT lifetimes, reject malformed numeric settings and name the correct session TTL setting in validation errors. Narrow consumer capabilities and move test controls to `@getstrata/core/testing`.
17
+
18
+ **Upgrade:** This release includes consumer API changes. Custom cache stores must implement `getOrSetTagged`; missing/unknown notification channels now fail explicitly, and the built-in database channel requires positive safe-integer user IDs. Move removed test-control imports to the dedicated testing entrypoint. Existing password-confirmation cookies require one fresh confirmation; normal sessions remain valid. Custom callers of `verifyOAuthState` must issue the matching browser-state cookie. SAML browser flows require HTTPS. See [the release notes](../../docs/releases/3.0.6.md) and [migration decisions](../../docs/architecture/solid-laravel-bun-followup.md).
19
+
20
+ ## 3.0.5
21
+
22
+ - Fixed SQLite queries returning no rows when SQL begins with comments, including VALUES, PRAGMA, EXPLAIN, and compact RETURNING statements.
23
+ - Aligned memory and Redis cache expiration. Added put and forever to ordinary, tagged, and execution-scoped caches. Zero or negative TTLs now remove entries; invalid numeric TTLs are rejected before effects.
24
+ - Fixed stale cache loaders overwriting newer writes and empty cache keys bypassing memory limits.
25
+ - Fixed internal redirect validation bypasses and preserved repeated query parameters.
26
+ - Fixed malformed intended-URL and flash cookies throwing errors.
27
+ - Fixed CI package dry-runs failing when the package version was already published.
28
+
29
+ **Migration:** Replace Redis TTL 0 used for permanent storage with forever(). For a permanent configured default, use `null`. TTL units remain milliseconds.
30
+
3
31
  ## 3.0.4
4
32
 
5
33
  Restore workspace-based npm publication and remove custom archive packing/recovery. Skip confirmed existing versions, stop on registry lookup failures, and accept successful npm uploads without requiring immediate registry visibility. Retain release quality gates, pinned npm, provenance and publication dry-runs. The v3.0.3 attempt published only @getstrata/core before its visibility check failed.
package/README.md CHANGED
@@ -14,7 +14,8 @@ Apps, and anything they import, should use subpaths:
14
14
 
15
15
  ```typescript
16
16
  import { createAuthMiddleware } from "@getstrata/core/http/authMiddleware";
17
- import { bindDatabaseConnection } from "@getstrata/core/database/bindConnection";
17
+ import { createModel } from "@getstrata/core/database/model";
18
+ import { defineTable } from "@getstrata/core/database/table";
18
19
  import { BaseRepository } from "@getstrata/core/database/baseRepository";
19
20
  import { FormRequest } from "@getstrata/core/http/formRequest";
20
21
  import { Policy } from "@getstrata/core/auth/policy";
@@ -23,17 +24,20 @@ import { ValidationError } from "@getstrata/core/errors/http";
23
24
  import type { Migration } from "@getstrata/core/database/migrations/types";
24
25
  ```
25
26
 
26
- The root `@getstrata/core` import resolves, but nothing stops you from ending up with two copies of process-wide state: the database pool, the dialect override, async-local auth and tenant context, and the `HttpError` base class used with `instanceof`. Some subpaths re-export the main bundle for exactly that reason. Prefer subpaths everywhere and the problem does not arise.
27
+ Prefer focused subpaths for application imports and keep test seams on
28
+ `@getstrata/core/testing`.
27
29
 
28
30
  ## Database
29
31
 
30
- Set `DATABASE_URL` before the first query; the connection is created lazily.
32
+ The application owns its connection and execution sessions. Configure its selected
33
+ engine at startup, then use `database.model(definition)` or
34
+ `database.repository(definition)` from the current execution. Transactions select
35
+ models and repositories from their supplied transaction session. Global default
36
+ pools, named-connection registries and `bindBunSql` are retired.
31
37
 
32
- ```typescript
33
- process.env.DATABASE_URL ??= "postgresql://postgres:postgres@localhost:5432/myapp";
34
- ```
35
-
36
- The engine is your choice, and an app should have one primary engine. Postgres apps use Bun's built-in `Bun.sql` through `createBunSqlPool()`, then `registerDefaultDatabasePool()` and `bindDatabaseConnection()`; `bindBunSql()` registers both. SQLite and MySQL register through `database/sqliteConnection` and `database/mysqlConnection`, or `registerNamedConnection` from `database/namedConnections`.
38
+ Use `createModel` and `defineTable` for ordinary models. Custom repository,
39
+ connection and adapter APIs remain available for advanced integrations; see the
40
+ [database guide](https://github.com/EyK-26/strata/blob/main/docs/DATABASE.md).
37
41
 
38
42
  `orderBy` takes `{ column, direction }` objects or column shorthand such as `{ published_at: "desc" }`. `{ ilike }` uses the value as-is, so pass `%term%` yourself.
39
43
 
@@ -49,7 +53,7 @@ Full-text `tsMatch` is PostgreSQL only.
49
53
 
50
54
  - `AdminResourceRegistry`, `formatAdminValue`: read-only resource browsers
51
55
  - `createFailedJobService`, `FailedJobService.delete()`: failed job persistence and cleanup
52
- - `runQueueJob`, `jobRegistry`: dispatch retried jobs from admin UIs
56
+ - `runQueueJob` with an application-owned job registry: dispatch retried jobs from admin UIs
53
57
 
54
58
  Generated apps do not include an admin dashboard, and the registry is optional.
55
59
 
@@ -62,3 +66,7 @@ Generated apps do not include an admin dashboard, and the registry is optional.
62
66
  - [Production](https://github.com/EyK-26/strata/blob/main/docs/PRODUCTION.md)
63
67
 
64
68
  Contributing to the framework itself: [CONTRIBUTING.md](https://github.com/EyK-26/strata/blob/main/CONTRIBUTING.md).
69
+
70
+ Test fixtures import loader, DNS and throttle controls from `@getstrata/core/testing`.
71
+ These controls share the package's private runtime state and are absent from the root
72
+ and every production subpath. Restore changed controls after each test.
@@ -24,5 +24,8 @@ declare class PolicyGate<Policies extends {
24
24
  allows<Resource extends keyof Policies & string, Action extends PolicyAction<Policies[Resource]>>(resource: Resource, action: Action, user: PolicyArguments<Policies[Resource][Action]>[0], ...model: PolicyArguments<Policies[Resource][Action]> extends [unknown?, ...infer Rest] ? Rest : never): Promise<boolean>;
25
25
  authorize<Resource extends keyof Policies & string, Action extends PolicyAction<Policies[Resource]>>(resource: Resource, action: Action, user: PolicyArguments<Policies[Resource][Action]>[0], ...model: PolicyArguments<Policies[Resource][Action]> extends [unknown?, ...infer Rest] ? Rest : never): Promise<void>;
26
26
  }
27
- export type { PolicyAction, PolicyDecision };
27
+ /** Consumer decisions and composition registration are separate capabilities. */
28
+ type PolicyAuthorizer = Pick<PolicyGate, "allows" | "authorize">;
29
+ type PolicyRegistry = Pick<PolicyGate, "register">;
30
+ export type { PolicyAction, PolicyAuthorizer, PolicyDecision, PolicyRegistry };
28
31
  export { Policy, PolicyDeniedError, PolicyGate };
@@ -53,10 +53,9 @@ type NodeSamlClient = {
53
53
  }>;
54
54
  };
55
55
  declare function readSamlEnvOptions(env?: Readonly<Record<string, string | undefined>>): SamlServiceProviderConfig;
56
- type NodeSamlModule = {
56
+ export type NodeSamlModule = {
57
57
  SAML: new (options: Record<string, unknown>) => NodeSamlClient;
58
58
  };
59
- declare function setNodeSamlLoaderForTests(loader: (() => Promise<NodeSamlModule>) | null): void;
60
59
  declare class SamlServiceProvider {
61
60
  private client;
62
61
  private readonly options;
@@ -68,4 +67,4 @@ declare class SamlServiceProvider {
68
67
  }
69
68
  declare function createSamlServiceProvider(options: SamlServiceProviderOptions): SamlServiceProvider;
70
69
  export type { SamlAssertionReplayStore, SamlServiceProviderConfig, SamlServiceProviderOptions };
71
- export { createSamlServiceProvider, createSqlSamlAssertionReplayStore, InMemorySamlAssertionReplayStore, REPLAY_RETENTION_MS, readSamlEnvOptions, SamlServiceProvider, setNodeSamlLoaderForTests, };
70
+ export { createSamlServiceProvider, createSqlSamlAssertionReplayStore, InMemorySamlAssertionReplayStore, REPLAY_RETENTION_MS, readSamlEnvOptions, SamlServiceProvider, };
@@ -3,7 +3,7 @@ import type { CacheStore } from "./store";
3
3
  type CacheDriver = "array" | "redis";
4
4
  interface CreateCacheStoreOptions {
5
5
  driver: CacheDriver;
6
- ttlMs: number;
6
+ ttlMs: number | null;
7
7
  maxEntries: number;
8
8
  redisUrl?: string;
9
9
  redis?: Readonly<RedisCacheOptions>;
@@ -0,0 +1,2 @@
1
+ /** null explicitly means forever; undefined selects the configured default. */
2
+ export declare function resolveCacheTtl(ttlMs: unknown, defaultTtlMs: number | null): number | null;
@@ -1,2 +1,2 @@
1
- declare const CACHE_SCRIPT = "\nlocal expected = {'hash', 'zset', 'zset', 'hash', 'zset'}\nfor i, key in ipairs(KEYS) do\n local kind = redis.call('TYPE', key).ok\n if kind ~= 'none' and kind ~= expected[i] then return redis.error_reply('Unexpected cache key type') end\nend\n-- Redis eviction can remove one container without its companions. Never read\n-- orphaned values or leases after losing the expiry/order/generation indexes.\nlocal entries = redis.call('HLEN', KEYS[1])\nlocal order = redis.call('ZCARD', KEYS[3])\nif redis.call('ZCARD', KEYS[2]) ~= order or entries ~= (order > 0 and order + 1 or 0) then\n redis.call('DEL', KEYS[1], KEYS[2], KEYS[3])\nend\nif redis.call('HLEN', KEYS[4]) ~= redis.call('ZCARD', KEYS[5]) then\n redis.call('DEL', KEYS[4], KEYS[5])\nend\nlocal r = cjson.decode(ARGV[1])\nlocal time = redis.call('TIME')\nlocal now = tonumber(time[1]) * 1000 + tonumber(time[2]) / 1000\nlocal function removeEntry(key)\n local removed = redis.call('HDEL', KEYS[1], 'e:' .. key)\n redis.call('ZREM', KEYS[2], key)\n redis.call('ZREM', KEYS[3], key)\n return removed\nend\nlocal function removeMeta(field)\n redis.call('HDEL', KEYS[4], field)\n redis.call('ZREM', KEYS[5], field)\nend\nfor _, key in ipairs(redis.call('ZRANGEBYSCORE', KEYS[2], '-inf', now, 'LIMIT', 0, r.capacity)) do removeEntry(key) end\nfor _, field in ipairs(redis.call('ZRANGEBYSCORE', KEYS[5], '-inf', now, 'LIMIT', 0, r.metadataLimit)) do removeMeta(field) end\nlocal function expireContainers()\n local last = redis.call('ZREVRANGE', KEYS[2], 0, 0, 'WITHSCORES')\n if #last == 0 then\n redis.call('DEL', KEYS[1], KEYS[2], KEYS[3])\n elseif last[2] == 'inf' then\n for i = 1, 3 do redis.call('PERSIST', KEYS[i]) end\n else\n local ttl = math.max(1, math.ceil(tonumber(last[2]) - now))\n for i = 1, 3 do redis.call('PEXPIRE', KEYS[i], ttl) end\n end\n for i = 4, 5 do redis.call('PEXPIRE', KEYS[i], r.metadataTtlMs) end\nend\nlocal function response(value)\n expireContainers()\n return cjson.encode(value)\nend\nlocal function addTags(existing, added)\n local seen = {}\n local result = {}\n for _, tags in ipairs({existing, added}) do\n for _, tag in ipairs(tags) do\n if not seen[tag] then seen[tag] = true; table.insert(result, tag) end\n end\n end\n if #result > 32 then error('Cache entries support at most 32 tags') end\n return result\nend\nlocal function touch(key)\n local sequence = redis.call('HINCRBY', KEYS[1], '_sequence', 1)\n redis.call('ZADD', KEYS[3], sequence, key)\nend\nlocal function read(key, tags)\n local raw = redis.call('HGET', KEYS[1], 'e:' .. key)\n if not raw then return nil end\n local entry = cjson.decode(raw)\n if #tags > 0 then\n entry.tags = addTags(entry.tags, tags)\n redis.call('HSET', KEYS[1], 'e:' .. key, cjson.encode(entry))\n end\n touch(key)\n return entry.payload\nend\nlocal function write(key, payload, tags)\n local entry = {payload=payload, tags=tags}\n redis.call('HSET', KEYS[1], 'e:' .. key, cjson.encode(entry))\n redis.call('ZADD', KEYS[2], r.ttlMs == 0 and '+inf' or now + r.ttlMs, key)\n touch(key)\n local overflow = redis.call('ZCARD', KEYS[3]) - r.capacity\n if overflow > 0 then\n for _, victim in ipairs(redis.call('ZRANGE', KEYS[3], 0, overflow - 1)) do removeEntry(victim) end\n end\nend\nlocal leaseField = 'l:' .. r.key\nlocal function lease()\n local raw = redis.call('HGET', KEYS[4], leaseField)\n if not raw then return nil end\n local value = cjson.decode(raw)\n if value.expires <= now or value.deadline <= now then removeMeta(leaseField); return nil end\n return value\nend\nlocal function metadataSpace(count)\n if redis.call('HLEN', KEYS[4]) + count > r.metadataLimit then\n -- Pressure sheds generation/lease state. Every old owner is fenced; cached\n -- entries remain valid because invalidation removes matching entries atomically.\n redis.call('DEL', KEYS[4], KEYS[5])\n end\nend\nlocal function putMeta(field, value, expires)\n redis.call('HSET', KEYS[4], field, value)\n redis.call('ZADD', KEYS[5], expires, field)\nend\nlocal function scopes()\n local fields = {}\n for _, tag in ipairs(r.tags) do table.insert(fields, 'g:tag:' .. tag) end\n for _, prefix in ipairs(r.prefixes) do table.insert(fields, 'g:prefix:' .. prefix) end\n return fields\nend\nlocal function matches(key, tags)\n if r.op == 'invalidate' then return key == r.key end\n if r.op == 'prefix' then return key == r.key or string.sub(key, 1, #r.key + 1) == r.key .. '?' end\n if r.op == 'tags' then\n for _, existing in ipairs(tags) do\n for _, wanted in ipairs(r.tags) do if wanted == existing then return true end end\n end\n end\n return false\nend\nif r.op == 'clear' then\n redis.call('DEL', unpack(KEYS))\n return cjson.encode({removed=0})\nelseif r.op == 'get' then\n local payload = read(r.key, r.tags)\n return response(payload and {kind='value', payload=payload} or {kind='missing'})\nelseif r.op == 'set' then\n local old = redis.call('HGET', KEYS[1], 'e:' .. r.key)\n local tags = old and cjson.decode(old).tags or {}\n write(r.key, r.payload, tags)\n removeMeta(leaseField)\n return response({written=true})\nelseif r.op == 'attach' then\n read(r.key, r.tags)\n return response({written=true})\nelseif r.op == 'size' then\n return response({size=redis.call('ZCARD', KEYS[3])})\nelseif r.op == 'tags' or r.op == 'prefix' or r.op == 'invalidate' then\n local generationFields = {}\n if r.op == 'tags' then\n for _, tag in ipairs(r.tags) do table.insert(generationFields, 'g:tag:' .. tag) end\n elseif r.op == 'prefix' then table.insert(generationFields, 'g:prefix:' .. r.key) end\n metadataSpace(#generationFields)\n for _, field in ipairs(generationFields) do putMeta(field, r.owner, now + r.metadataTtlMs) end\n local removed = 0\n for _, key in ipairs(redis.call('ZRANGE', KEYS[3], 0, -1)) do\n local raw = redis.call('HGET', KEYS[1], 'e:' .. key)\n if raw and matches(key, cjson.decode(raw).tags) then removed = removed + removeEntry(key) end\n end\n for _, field in ipairs(redis.call('HKEYS', KEYS[4])) do\n if string.sub(field, 1, 2) == 'l:' then\n local value = cjson.decode(redis.call('HGET', KEYS[4], field))\n if matches(string.sub(field, 3), value.tags) then removeMeta(field) end\n end\n end\n return response({removed=removed})\nelseif r.op == 'claim' then\n local payload = read(r.key, r.tags)\n if payload then return response({kind='value', payload=payload}) end\n local current = lease()\n if current then\n local shared = addTags(current.tags, r.tags)\n if #shared == #current.tags then return response({kind='wait'}) end\n -- A newly requested tag must not inherit a fill started before that tag's\n -- invalidation. Restart with the union of tags and a new owner.\n r.tags = shared\n removeMeta(leaseField)\n end\n local active = 0\n for _, field in ipairs(redis.call('HKEYS', KEYS[4])) do if string.sub(field, 1, 2) == 'l:' then active = active + 1 end end\n if active >= r.capacity then return response({kind='wait'}) end\n local fields = scopes()\n metadataSpace(#fields + 1)\n local generations = {}\n for _, field in ipairs(fields) do\n local token = redis.call('HGET', KEYS[4], field) or r.owner\n putMeta(field, token, now + r.metadataTtlMs)\n generations[field] = token\n end\n local value = {owner=r.owner, tags=r.tags, generations=generations, deadline=now + r.fillTimeoutMs, expires=now + r.leaseMs}\n putMeta(leaseField, cjson.encode(value), value.expires)\n return response({kind='owner'})\nelseif r.op == 'renew' or r.op == 'publish' or r.op == 'release' then\n local current = lease()\n if not current or current.owner ~= r.owner then return response({owned=false}) end\n if r.op == 'release' then removeMeta(leaseField); return response({owned=true}) end\n for field, token in pairs(current.generations) do\n if redis.call('HGET', KEYS[4], field) ~= token then removeMeta(leaseField); return response({owned=false}) end\n end\n if r.op == 'renew' then\n current.expires = math.min(current.deadline, now + r.leaseMs)\n putMeta(leaseField, cjson.encode(current), current.expires)\n else\n write(r.key, r.payload, current.tags)\n removeMeta(leaseField)\n end\n return response({owned=true})\nend\nreturn redis.error_reply('Unknown cache operation')\n";
1
+ declare const CACHE_SCRIPT = "\nlocal expected = {'hash', 'zset', 'zset', 'hash', 'zset'}\nfor i, key in ipairs(KEYS) do\n local kind = redis.call('TYPE', key).ok\n if kind ~= 'none' and kind ~= expected[i] then return redis.error_reply('Unexpected cache key type') end\nend\n-- Redis eviction can remove one container without its companions. Never read\n-- orphaned values or leases after losing the expiry/order/generation indexes.\nlocal entries = redis.call('HLEN', KEYS[1])\nlocal order = redis.call('ZCARD', KEYS[3])\nif redis.call('ZCARD', KEYS[2]) ~= order or entries ~= (order > 0 and order + 1 or 0) then\n redis.call('DEL', KEYS[1], KEYS[2], KEYS[3])\nend\nif redis.call('HLEN', KEYS[4]) ~= redis.call('ZCARD', KEYS[5]) then\n redis.call('DEL', KEYS[4], KEYS[5])\nend\nlocal r = cjson.decode(ARGV[1])\nlocal time = redis.call('TIME')\nlocal now = tonumber(time[1]) * 1000 + tonumber(time[2]) / 1000\nlocal function removeEntry(key)\n local removed = redis.call('HDEL', KEYS[1], 'e:' .. key)\n redis.call('ZREM', KEYS[2], key)\n redis.call('ZREM', KEYS[3], key)\n return removed\nend\nlocal function removeMeta(field)\n redis.call('HDEL', KEYS[4], field)\n redis.call('ZREM', KEYS[5], field)\nend\nfor _, key in ipairs(redis.call('ZRANGEBYSCORE', KEYS[2], '-inf', now, 'LIMIT', 0, r.capacity)) do removeEntry(key) end\nfor _, field in ipairs(redis.call('ZRANGEBYSCORE', KEYS[5], '-inf', now, 'LIMIT', 0, r.metadataLimit)) do removeMeta(field) end\nlocal function expireContainers()\n local last = redis.call('ZREVRANGE', KEYS[2], 0, 0, 'WITHSCORES')\n if #last == 0 then\n redis.call('DEL', KEYS[1], KEYS[2], KEYS[3])\n elseif last[2] == 'inf' then\n for i = 1, 3 do redis.call('PERSIST', KEYS[i]) end\n else\n local ttl = math.max(1, math.ceil(tonumber(last[2]) - now))\n for i = 1, 3 do redis.call('PEXPIRE', KEYS[i], ttl) end\n end\n for i = 4, 5 do redis.call('PEXPIRE', KEYS[i], r.metadataTtlMs) end\nend\nlocal function response(value)\n expireContainers()\n return cjson.encode(value)\nend\nlocal function addTags(existing, added)\n local seen = {}\n local result = {}\n for _, tags in ipairs({existing, added}) do\n for _, tag in ipairs(tags) do\n if not seen[tag] then seen[tag] = true; table.insert(result, tag) end\n end\n end\n if #result > 32 then error('Cache entries support at most 32 tags') end\n return result\nend\nlocal function touch(key)\n local sequence = redis.call('HINCRBY', KEYS[1], '_sequence', 1)\n redis.call('ZADD', KEYS[3], sequence, key)\nend\nlocal function read(key, tags)\n local raw = redis.call('HGET', KEYS[1], 'e:' .. key)\n if not raw then return nil end\n local entry = cjson.decode(raw)\n if #tags > 0 then\n entry.tags = addTags(entry.tags, tags)\n redis.call('HSET', KEYS[1], 'e:' .. key, cjson.encode(entry))\n end\n touch(key)\n return entry.payload\nend\nlocal function write(key, payload, tags)\n if not r.forever and r.ttlMs <= 0 then removeEntry(key); return end\n local entry = {payload=payload, tags=tags}\n redis.call('HSET', KEYS[1], 'e:' .. key, cjson.encode(entry))\n redis.call('ZADD', KEYS[2], r.forever and '+inf' or now + r.ttlMs, key)\n touch(key)\n local overflow = redis.call('ZCARD', KEYS[3]) - r.capacity\n if overflow > 0 then\n for _, victim in ipairs(redis.call('ZRANGE', KEYS[3], 0, overflow - 1)) do removeEntry(victim) end\n end\nend\nlocal leaseField = 'l:' .. r.key\nlocal function lease()\n local raw = redis.call('HGET', KEYS[4], leaseField)\n if not raw then return nil end\n local value = cjson.decode(raw)\n if value.expires <= now or value.deadline <= now then removeMeta(leaseField); return nil end\n return value\nend\nlocal function metadataSpace(count)\n if redis.call('HLEN', KEYS[4]) + count > r.metadataLimit then\n -- Pressure sheds generation/lease state. Every old owner is fenced; cached\n -- entries remain valid because invalidation removes matching entries atomically.\n redis.call('DEL', KEYS[4], KEYS[5])\n end\nend\nlocal function putMeta(field, value, expires)\n redis.call('HSET', KEYS[4], field, value)\n redis.call('ZADD', KEYS[5], expires, field)\nend\nlocal function scopes()\n local fields = {}\n for _, tag in ipairs(r.tags) do table.insert(fields, 'g:tag:' .. tag) end\n for _, prefix in ipairs(r.prefixes) do table.insert(fields, 'g:prefix:' .. prefix) end\n return fields\nend\nlocal function matches(key, tags)\n if r.op == 'invalidate' then return key == r.key end\n if r.op == 'prefix' then return key == r.key or string.sub(key, 1, #r.key + 1) == r.key .. '?' end\n if r.op == 'tags' then\n for _, existing in ipairs(tags) do\n for _, wanted in ipairs(r.tags) do if wanted == existing then return true end end\n end\n end\n return false\nend\nif r.op == 'clear' then\n redis.call('DEL', unpack(KEYS))\n return cjson.encode({removed=0})\nelseif r.op == 'get' then\n local payload = read(r.key, r.tags)\n return response(payload and {kind='value', payload=payload} or {kind='missing'})\nelseif r.op == 'set' then\n local old = redis.call('HGET', KEYS[1], 'e:' .. r.key)\n local tags = addTags(old and cjson.decode(old).tags or {}, r.tags)\n write(r.key, r.payload, tags)\n removeMeta(leaseField)\n return response({written=true})\nelseif r.op == 'attach' then\n read(r.key, r.tags)\n return response({written=true})\nelseif r.op == 'size' then\n return response({size=redis.call('ZCARD', KEYS[3])})\nelseif r.op == 'tags' or r.op == 'prefix' or r.op == 'invalidate' then\n local generationFields = {}\n if r.op == 'tags' then\n for _, tag in ipairs(r.tags) do table.insert(generationFields, 'g:tag:' .. tag) end\n elseif r.op == 'prefix' then table.insert(generationFields, 'g:prefix:' .. r.key) end\n metadataSpace(#generationFields)\n for _, field in ipairs(generationFields) do putMeta(field, r.owner, now + r.metadataTtlMs) end\n local removed = 0\n for _, key in ipairs(redis.call('ZRANGE', KEYS[3], 0, -1)) do\n local raw = redis.call('HGET', KEYS[1], 'e:' .. key)\n if raw and matches(key, cjson.decode(raw).tags) then removed = removed + removeEntry(key) end\n end\n for _, field in ipairs(redis.call('HKEYS', KEYS[4])) do\n if string.sub(field, 1, 2) == 'l:' then\n local value = cjson.decode(redis.call('HGET', KEYS[4], field))\n if matches(string.sub(field, 3), value.tags) then removeMeta(field) end\n end\n end\n return response({removed=removed})\nelseif r.op == 'claim' then\n local payload = read(r.key, r.tags)\n if payload then return response({kind='value', payload=payload}) end\n local current = lease()\n if current then\n local shared = addTags(current.tags, r.tags)\n if #shared == #current.tags then return response({kind='wait'}) end\n -- A newly requested tag must not inherit a fill started before that tag's\n -- invalidation. Restart with the union of tags and a new owner.\n r.tags = shared\n removeMeta(leaseField)\n end\n local active = 0\n for _, field in ipairs(redis.call('HKEYS', KEYS[4])) do if string.sub(field, 1, 2) == 'l:' then active = active + 1 end end\n if active >= r.capacity then return response({kind='wait'}) end\n local fields = scopes()\n metadataSpace(#fields + 1)\n local generations = {}\n for _, field in ipairs(fields) do\n local token = redis.call('HGET', KEYS[4], field) or r.owner\n putMeta(field, token, now + r.metadataTtlMs)\n generations[field] = token\n end\n local value = {owner=r.owner, tags=r.tags, generations=generations, deadline=now + r.fillTimeoutMs, expires=now + r.leaseMs}\n putMeta(leaseField, cjson.encode(value), value.expires)\n return response({kind='owner'})\nelseif r.op == 'renew' or r.op == 'publish' or r.op == 'release' then\n local current = lease()\n if not current or current.owner ~= r.owner then return response({owned=false}) end\n if r.op == 'release' then removeMeta(leaseField); return response({owned=true}) end\n for field, token in pairs(current.generations) do\n if redis.call('HGET', KEYS[4], field) ~= token then removeMeta(leaseField); return response({owned=false}) end\n end\n if r.op == 'renew' then\n current.expires = math.min(current.deadline, now + r.leaseMs)\n putMeta(leaseField, cjson.encode(current), current.expires)\n else\n write(r.key, r.payload, current.tags)\n removeMeta(leaseField)\n end\n return response({owned=true})\nend\nreturn redis.error_reply('Unknown cache operation')\n";
2
2
  export { CACHE_SCRIPT };
@@ -10,7 +10,7 @@ type RedisCacheOptions = {
10
10
  };
11
11
  declare const DEFAULT_CACHE_NAMESPACE = "strata:cache:v3:";
12
12
  declare function validateCacheNamespace(namespace: string): void;
13
- declare function normalizeRedisCacheOptions(ttlMs: number, maxEntries: number, options?: Readonly<RedisCacheOptions>): Readonly<Required<RedisCacheOptions>>;
13
+ declare function normalizeRedisCacheOptions(ttlMs: number | null, maxEntries: number, options?: Readonly<RedisCacheOptions>): Readonly<Required<RedisCacheOptions>>;
14
14
  declare class RedisCacheStore implements CacheStore {
15
15
  private readonly redisUrl;
16
16
  private readonly ttlMs;
@@ -20,13 +20,13 @@ declare class RedisCacheStore implements CacheStore {
20
20
  private readonly options;
21
21
  private readonly fills;
22
22
  private closed;
23
- constructor(redisUrl: string, ttlMs: number, maxEntries: number, options?: RedisCacheOptions, namespace?: string);
23
+ constructor(redisUrl: string, ttlMs: number | null, maxEntries: number, options?: RedisCacheOptions, namespace?: string);
24
24
  private createClient;
25
25
  close(): void;
26
26
  get<T>(key: string): Promise<T | undefined>;
27
- set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
28
- getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
29
- getOrSetTagged<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
27
+ set<T>(key: string, value: T, ttlMs?: number | null, tags?: string[]): Promise<void>;
28
+ getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number | null): Promise<T>;
29
+ getOrSetTagged<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, tags: string[], ttlMs?: number | null): Promise<T>;
30
30
  attachTags(key: string, tags: string[]): Promise<void>;
31
31
  flushTags(tags: string[]): Promise<number>;
32
32
  invalidate(key: string): Promise<boolean>;
@@ -7,6 +7,8 @@ declare class CacheRepository {
7
7
  constructor(store: CacheStore);
8
8
  close(): Promise<void>;
9
9
  get<T>(key: string): Promise<T | undefined>;
10
+ put<T>(key: string, value: T, ttlMs?: number): Promise<void>;
11
+ forever<T>(key: string, value: T): Promise<void>;
10
12
  remember<T>(key: string, callback: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
11
13
  forget(key: string): Promise<boolean>;
12
14
  flush(): Promise<void>;
@@ -1,4 +1,4 @@
1
- declare function validateSimpleCacheOptions(ttlMs: number, maxEntries: number): void;
1
+ declare function validateSimpleCacheOptions(ttlMs: number | null, maxEntries: number): void;
2
2
  declare class SimpleCache {
3
3
  private readonly ttlMs;
4
4
  private readonly maxEntries;
@@ -6,11 +6,11 @@ declare class SimpleCache {
6
6
  private readonly inflight;
7
7
  private readonly tagIndex;
8
8
  private readonly keyTags;
9
- constructor(ttlMs?: number, maxEntries?: number);
9
+ constructor(ttlMs?: number | null, maxEntries?: number);
10
10
  get<T>(key: string): T | undefined;
11
- set<T>(key: string, value: T, ttlMs?: number): void;
12
- getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
13
- getOrSetTagged<T>(key: string, loader: () => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
11
+ set<T>(key: string, value: T, ttlMs?: number | null, tags?: string[]): void;
12
+ getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number | null): Promise<T>;
13
+ getOrSetTagged<T>(key: string, loader: () => Promise<T>, tags: string[], ttlMs?: number | null): Promise<T>;
14
14
  attachTags(key: string, tags: string[]): void;
15
15
  flushTags(tags: string[]): number;
16
16
  invalidate(key: string): boolean;
@@ -4,9 +4,9 @@ declare class SimpleCacheStore implements CacheStore {
4
4
  private readonly cache;
5
5
  constructor(cache: SimpleCache);
6
6
  get<T>(key: string): Promise<T | undefined>;
7
- set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
8
- getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
9
- getOrSetTagged<T>(key: string, loader: () => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
7
+ set<T>(key: string, value: T, ttlMs?: number | null, tags?: string[]): Promise<void>;
8
+ getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number | null): Promise<T>;
9
+ getOrSetTagged<T>(key: string, loader: () => Promise<T>, tags: string[], ttlMs?: number | null): Promise<T>;
10
10
  attachTags(key: string, tags: string[]): Promise<void>;
11
11
  flushTags(tags: string[]): Promise<number>;
12
12
  invalidate(key: string): Promise<boolean>;
@@ -1,10 +1,11 @@
1
1
  interface CacheStore {
2
2
  close?(): void | Promise<void>;
3
3
  get<T>(key: string): Promise<T | undefined>;
4
- set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
5
- getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
6
- /** Shared stores can bind tags before starting a fill. */
7
- getOrSetTagged?<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
4
+ /** null is forever; nonpositive TTLs remove the key and fence pending fills. */
5
+ set<T>(key: string, value: T, ttlMs?: number | null, tags?: string[]): Promise<void>;
6
+ getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number | null): Promise<T>;
7
+ /** Bind tags before loading; publication and invalidation must share ownership. */
8
+ getOrSetTagged<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, tags: string[], ttlMs?: number | null): Promise<T>;
8
9
  attachTags(key: string, tags: string[]): Promise<void>;
9
10
  flushTags(tags: string[]): Promise<number>;
10
11
  invalidate(key: string): Promise<boolean>;
@@ -3,6 +3,8 @@ declare class TaggedCache {
3
3
  private readonly store;
4
4
  private readonly tags;
5
5
  constructor(store: CacheStore, tags: string[]);
6
+ put<T>(key: string, value: T, ttlMs?: number): Promise<void>;
7
+ forever<T>(key: string, value: T): Promise<void>;
6
8
  remember<T>(key: string, callback: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
7
9
  flush(): Promise<number>;
8
10
  }
@@ -4,5 +4,5 @@ import type { CacheRepository } from "./repository";
4
4
  declare const CORE_CACHE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<CacheLike>;
5
5
  /** Internal application backend; execution consumers depend on CORE_CACHE_TOKEN. */
6
6
  declare const CORE_CACHE_BACKEND_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<CacheRepository>;
7
- export type { CacheLike };
7
+ export type { CacheLike, CacheReader, CacheWriter } from "../../types/services";
8
8
  export { CORE_CACHE_BACKEND_TOKEN, CORE_CACHE_TOKEN };
@@ -11,3 +11,16 @@ declare function defineEnvSchema<const Schema extends EnvSchema>(schema: Schema)
11
11
  declare function validateEnv(schema: EnvSchema, env?: Readonly<Record<string, string | undefined>>): Record<string, string>;
12
12
  export type { EnvRule, EnvSchema };
13
13
  export { defineEnvSchema, validateEnv };
14
+ type BlankDefault<Value extends string> = Value extends `${" " | "\t" | "\r" | "\n"}${infer Rest}` ? BlankDefault<Rest> : Value extends "" ? true : false;
15
+ type ResolvedRule<Rule extends EnvRule> = Rule extends {
16
+ integer: true;
17
+ } ? number : string;
18
+ export type ResolvedEnv<Schema extends EnvSchema> = Readonly<{
19
+ [Name in keyof Schema]: Schema[Name] extends {
20
+ required: true;
21
+ } ? ResolvedRule<Schema[Name]> : Schema[Name] extends {
22
+ default: infer Default extends string;
23
+ } ? BlankDefault<Default> extends true ? ResolvedRule<Schema[Name]> | undefined : ResolvedRule<Schema[Name]> : ResolvedRule<Schema[Name]> | undefined;
24
+ }>;
25
+ /** Validate once and freeze a typed snapshot; blanks keep validateEnv's default semantics. */
26
+ export declare function resolveEnv<const Schema extends EnvSchema>(schema: Schema, env?: Readonly<Record<string, string | undefined>>): ResolvedEnv<Schema>;
@@ -75,8 +75,12 @@ interface ProviderScope {
75
75
  }
76
76
  interface ProviderDefinition {
77
77
  readonly name: string;
78
+ /** Declarative bindings compiled into the application graph before any setup runs. */
79
+ readonly services?: readonly ServiceDeclaration[];
78
80
  readonly requires?: readonly string[];
79
81
  readonly setup: (scope: ProviderScope) => void | Promise<void>;
82
+ /** Runs after every provider setup, before transports start. */
83
+ readonly boot?: (scope: ProviderScope) => void | Promise<void>;
80
84
  }
81
85
  /** Uses the same owner as providers and starts after all providers have finished setup. */
82
86
  type TransportDefinition = ProviderDefinition;
@@ -1,5 +1,5 @@
1
1
  import type { CacheLike } from "../../types/services";
2
- import type { StorageManager } from "../storage/storage";
2
+ import type { Storage } from "../storage/storage";
3
3
  import type { ConfigStore, ConfigStoreLike, ServiceContainer, ServiceFactory, ServiceToken } from "./container";
4
4
  import type { PersistenceInvocation } from "./persistence";
5
5
  type AppRouteMap = Record<string, any>;
@@ -8,7 +8,7 @@ interface AppDependencies {
8
8
  readonly invoke: PersistenceInvocation;
9
9
  container: ServiceContainer;
10
10
  cache: CacheLike;
11
- storage: StorageManager;
11
+ storage: Storage;
12
12
  }
13
13
  type MutableAppDependencies = Partial<Omit<AppDependencies, "container">> & Pick<AppDependencies, "container">;
14
14
  interface ProviderContext {
@@ -0,0 +1,13 @@
1
+ import type { ProviderDefinition, ProviderScope } from "./application";
2
+ import type { ServiceDeclaration } from "./services";
3
+ interface ApplicationProviderOptions {
4
+ readonly name: string;
5
+ readonly requires?: readonly string[];
6
+ readonly services?: readonly ServiceDeclaration[];
7
+ readonly setup?: (scope: ProviderScope) => void | Promise<void>;
8
+ readonly boot?: (scope: ProviderScope) => void | Promise<void>;
9
+ }
10
+ /** Group declarative bindings and startup hooks without introducing a mutable container. */
11
+ declare function defineProvider(options: ApplicationProviderOptions): ProviderDefinition;
12
+ export type { ApplicationProviderOptions };
13
+ export { defineProvider };
@@ -1,12 +1,12 @@
1
1
  import type { AbilityChecker } from "../auth/abilityChecker";
2
2
  import type { AuthReader } from "../auth/authReader";
3
- import type { PolicyGate } from "../auth/policy";
4
- import type { EventBus } from "../events/eventBusClass";
3
+ import type { PolicyAuthorizer, PolicyRegistry } from "../auth/policy";
4
+ import type { EventDispatcher } from "../events/eventBusClass";
5
5
  import type { ThrottleQuotaPolicy } from "../http/throttleMiddleware";
6
- import type { Mailer } from "../mail/mailer";
7
- import type { Queue } from "../queue/index";
6
+ import type { MailSender } from "../mail/mailer";
7
+ import type { QueueDispatcher } from "../queue/index";
8
8
  import type { QueueServices } from "../queue/queueServices";
9
- import type { StorageManager } from "../storage/storage";
9
+ import type { Storage } from "../storage/storage";
10
10
  import type { PublicTenancyOptions, TenantResolver } from "../tenant/tenantMiddleware";
11
11
  import type { TracingRuntime } from "../tracing/otel";
12
12
  import type { AuthAccountLookup } from "./authUserDirectory";
@@ -17,16 +17,17 @@ declare const CORE_PUBLIC_TENANCY_TOKEN: import("@getstrata/core/contracts/token
17
17
  declare const CORE_TENANT_RESOLVER_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<TenantResolver>;
18
18
  declare const CORE_HTTP_CLEANUP_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<(cleanup: () => void) => void>;
19
19
  declare const CORE_TRACING_RUNTIME_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<TracingRuntime>;
20
- declare const CORE_MAIL_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<Mailer>;
21
- declare const CORE_STORAGE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<StorageManager>;
20
+ declare const CORE_MAIL_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<MailSender>;
21
+ declare const CORE_STORAGE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<Storage>;
22
22
  declare const CORE_JSON_RESPONSE_POLICY_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<Readonly<{
23
23
  etagEnabled: boolean;
24
24
  }>>;
25
25
  declare const CORE_CONFIG_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<ConfigStoreLike>;
26
26
  declare const FAILED_JOB_SERVICE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<QueueServices>;
27
- declare const CORE_QUEUE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<Queue>;
28
- declare const CORE_EVENT_BUS_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<EventBus>;
29
- declare const CORE_POLICY_GATE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<Pick<PolicyGate<Record<string, import("../auth/policy").Policy>>, "allows" | "authorize" | "register">>;
27
+ declare const CORE_QUEUE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<QueueDispatcher>;
28
+ declare const CORE_EVENT_BUS_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<EventDispatcher>;
29
+ declare const CORE_POLICY_GATE_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<PolicyAuthorizer>;
30
+ declare const CORE_POLICY_REGISTRY_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<PolicyRegistry>;
30
31
  declare const CORE_AUTH_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<AuthReader>;
31
32
  declare const CORE_ABILITY_CHECKER_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<AbilityChecker>;
32
33
  declare const CORE_AUTH_USER_DIRECTORY_TOKEN: import("@getstrata/core/contracts/token").ServiceToken<AuthAccountLookup>;
@@ -34,4 +35,4 @@ declare function isAbilityChecker(value: unknown): value is AbilityChecker;
34
35
  declare function isAuthUserDirectory(value: unknown): value is AuthAccountLookup;
35
36
  declare function resolveAbilityChecker(container: ServiceContainerLike): AbilityChecker;
36
37
  declare function resolveAuthUserDirectory(container: ServiceContainerLike): AuthAccountLookup | null;
37
- export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_HTTP_CLEANUP_TOKEN, CORE_JSON_RESPONSE_POLICY_TOKEN, CORE_MAIL_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_PUBLIC_TENANCY_TOKEN, CORE_QUEUE_TOKEN, CORE_STORAGE_TOKEN, CORE_TENANT_RESOLVER_TOKEN, CORE_THROTTLE_QUOTA_POLICY_TOKEN, CORE_TRACING_RUNTIME_TOKEN, FAILED_JOB_SERVICE_TOKEN, isAbilityChecker, isAuthUserDirectory, resolveAbilityChecker, resolveAuthUserDirectory, };
38
+ export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_HTTP_CLEANUP_TOKEN, CORE_JSON_RESPONSE_POLICY_TOKEN, CORE_MAIL_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_POLICY_REGISTRY_TOKEN, CORE_PUBLIC_TENANCY_TOKEN, CORE_QUEUE_TOKEN, CORE_STORAGE_TOKEN, CORE_TENANT_RESOLVER_TOKEN, CORE_THROTTLE_QUOTA_POLICY_TOKEN, CORE_TRACING_RUNTIME_TOKEN, FAILED_JOB_SERVICE_TOKEN, isAbilityChecker, isAuthUserDirectory, resolveAbilityChecker, resolveAuthUserDirectory, };
@@ -70,3 +70,6 @@ declare class Factory<TRecord extends object, Counted extends boolean = false> {
70
70
  }
71
71
  export type { FactoryBehavior, FactoryConstruction, FactoryDefinition, FactoryMakeResult, FactoryParent, FactoryPersist, StatelessFactoryConstruction, };
72
72
  export { defineFactory, Factory };
73
+ /** Create a factory with explicit persistence supplied by the active invocation. */
74
+ declare function createFactory<R extends object>(behavior: FactoryBehavior<R>): Factory<R>;
75
+ export { createFactory };
@@ -3,7 +3,7 @@ export { defineModel, defineRepository, repositoryEffects, } from "@getstrata/co
3
3
  export { mapDatabaseError, RecordNotFoundError, withDatabaseErrorHandling, } from "@getstrata/core/database/errors";
4
4
  export type { FactoryBehavior, FactoryConstruction, FactoryDefinition, FactoryMakeResult, FactoryParent, FactoryPersist, StatelessFactoryConstruction, } from "@getstrata/core/database/factory";
5
5
  export { defineFactory, Factory } from "@getstrata/core/database/factory";
6
- export { BaseRepository, BelongsToManyRelationQuery, BelongsToRelationQuery, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, Model, ModelQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, RepositoryQuery, } from "#strata-orm-runtime";
6
+ export { BaseRepository, BelongsToManyRelationQuery, BelongsToRelationQuery, createModel, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, Model, ModelQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, RepositoryQuery, } from "#strata-orm-runtime";
7
7
  export { createDatabaseConnection } from "./connection.ts";
8
8
  export type { ActiveDatabaseHandle } from "./connectionContext.ts";
9
9
  export { getActiveDatabaseConnection, hasActiveDatabaseConnection, runWithDatabaseConnection, } from "./connectionContext.ts";
@@ -0,0 +1,11 @@
1
+ import { type SchemaBuilder } from "../schema/schema";
2
+ import type { Migration, MigrationDatabase, MigrationDownContext } from "./types";
3
+ interface MigrationDeclaration {
4
+ readonly name: string;
5
+ readonly up: (schema: SchemaBuilder, db: MigrationDatabase) => void | Promise<void>;
6
+ readonly down: (schema: SchemaBuilder, db: MigrationDatabase, context?: MigrationDownContext) => void | Promise<void>;
7
+ }
8
+ /** The runner owns the database and dialect; declarations describe only schema changes. */
9
+ declare function defineMigration(declaration: MigrationDeclaration): Migration;
10
+ export type { MigrationDeclaration };
11
+ export { defineMigration };
@@ -21,7 +21,9 @@ declare function freshDatabase(db: MigrationDatabase, migrations: Migration[], o
21
21
  advisoryLock?: boolean;
22
22
  onMigration?: (name: string) => void;
23
23
  destructive?: boolean;
24
+ environment?: Readonly<Record<string, string | undefined>>;
24
25
  }): Promise<void>;
25
26
  export { withMigrationLock } from "./advisoryLock.ts";
27
+ export { defineMigration, type MigrationDeclaration } from "./declaration";
26
28
  export { guardMigrationRollback, type MigrationRollbackGuard } from "./rollbackGuard.ts";
27
29
  export { ensureMigrationsTable, freshDatabase, getAppliedMigrations, getMigrationStatus, loadMigrationsFromDirectory, migrateDatabase, rollbackDatabase, runPendingMigrations, };
@@ -1,12 +1,14 @@
1
- import type { AnyModelDefinition, ModelBinding, ModelDefinition, ModelObserver, ModelState } from "@getstrata/core/database/definitions";
1
+ import type { AnyModelDefinition, ModelAttributeOptions, ModelBinding, ModelDefinition, ModelObserver, ModelState, RepositoryDefinition } from "@getstrata/core/database/definitions";
2
+ import type { ServiceToken } from "../contracts/token";
2
3
  import type { KeysetOptions } from "../pagination/index.ts";
3
- import type BaseRepository from "./baseRepository.ts";
4
+ import BaseRepository from "./baseRepository.ts";
4
5
  import { applyCasts, type CastType, dehydrateValue, filterMassAssignable, hydrateValue, type LoadedAttributes, type ModelCasts } from "./modelAttributes.ts";
5
6
  import { type AnyModel, type ModelAttributes, type ModelIdentifier, type ModelProjection, ModelQuery, type RelationNameInput } from "./modelQuery.ts";
6
7
  import type { AnyRelationQuery, RelatedModelClass } from "./relationQuery.ts";
7
8
  import { BelongsToManyRelationQuery, BelongsToRelationQuery, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery } from "./relationQuery.ts";
8
9
  import type { BelongsToManyRelation, BelongsToRelation, HasManyRelation, HasOneRelation } from "./relationships.ts";
9
10
  import type { RepositoryQuery } from "./repositoryQuery.ts";
11
+ import type { TableDefinition } from "./table";
10
12
  import type { ModelWhere, ModelWriteValues, QueryOptions } from "./types.ts";
11
13
  type RelatedRef<TRelated extends object, RelatedKey extends keyof TRelated & string, M extends Model<TRelated, RelatedKey> = Model<TRelated, RelatedKey>> = ModelDefinition<TRelated, RelatedKey, M> | string | (() => ModelDefinition<TRelated, RelatedKey, M>);
12
14
  declare let saveRelatedModel: (entity: AnyModel, forced: LoadedAttributes) => Promise<AnyModel>;
@@ -167,7 +169,18 @@ declare class BoundModelFacade<R extends object, K extends keyof R & string, M e
167
169
  }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, values?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
168
170
  }
169
171
  declare function createBoundModel<R extends object, K extends keyof R & string, M extends Model<R, K>>(binding: ModelBinding<R, K, BaseRepository<R, K>>): BoundModelFacade<R, K, M>;
172
+ /** Declare an ordinary model without selecting a database session or constructing entities. */
173
+ declare function createModel<R extends object, K extends keyof R & string>(options: {
174
+ name: string;
175
+ table: TableDefinition<R, K>;
176
+ attributes: ModelAttributeOptions<R>;
177
+ aliases?: readonly string[];
178
+ observers?: readonly ServiceToken<ModelObserver<Model<R, K>>>[];
179
+ scopes?: readonly ((query: RepositoryQuery<R, K>) => RepositoryQuery<R, K>)[];
180
+ }): ModelDefinition<R, K, Model<R, K>> & {
181
+ readonly repository: RepositoryDefinition<R, K, BaseRepository<R, K>>;
182
+ };
170
183
  export { defineModel } from "@getstrata/core/database/definitions";
171
184
  export { BelongsToManyRelationQuery, BelongsToRelationQuery, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, } from "./relationQuery.ts";
172
185
  export type { CastType, ModelAttributes, ModelProjection, RelatedRef };
173
- export { applyCasts, BoundModelFacade, createBoundModel, dehydrateValue, filterMassAssignable, getModelBinding, hydrateValue, Model, ModelQuery, modelFacade, runObservers, saveRelatedModel, };
186
+ export { applyCasts, BoundModelFacade, createBoundModel, createModel, dehydrateValue, filterMassAssignable, getModelBinding, hydrateValue, Model, ModelQuery, modelFacade, runObservers, saveRelatedModel, };
@@ -1,6 +1,7 @@
1
1
  import type { CursorPaginatedResult, KeysetCursor, KeysetOptions } from "../pagination/index.ts";
2
2
  import type BaseRepository from "./baseRepository.ts";
3
3
  import { type Model } from "./model.ts";
4
+ import { flattenRelationNames, loadNested, type RelationNameInput } from "./modelRelationLoader";
4
5
  import type { AnyRelationQuery } from "./relationQuery.ts";
5
6
  import type { BelongsToManyRelation, BelongsToRelation, HasManyRelation, HasManyThroughRelation, MorphManyRelation, MorphOneRelation, MorphToRelation } from "./relationships.ts";
6
7
  import { type RepositoryQuery } from "./repositoryQuery.ts";
@@ -17,16 +18,6 @@ type WithModelCount<TModel, TCount extends string> = {
17
18
  get<K extends keyof (Omit<ModelAttributes<TModel>, TCount> & Record<TCount, unknown>)>(key: K): (Omit<ModelAttributes<TModel>, TCount> & Record<TCount, unknown>)[K];
18
19
  } & TModel;
19
20
  type ModelQueryResult<TModel, TCounts extends string> = [TCounts] extends [never] ? TModel : WithModelCount<TModel, TCounts>;
20
- type RelationNameInput = string | readonly string[];
21
- declare function flattenRelationNames(relations: ReadonlyArray<RelationNameInput>): string[];
22
- declare function loadNested(model: {
23
- load: (...names: string[]) => Promise<unknown>;
24
- loaded: (name: string) => unknown;
25
- constructor: object;
26
- getRepository: () => BaseRepository<Record<string, unknown>, "id">;
27
- toObject: () => object;
28
- setLoaded: (name: string, value: unknown) => unknown;
29
- }, path: string, preparedRoot?: AnyRelationQuery): Promise<void>;
30
21
  /** Read-only plain records; partial selection never acquires model mutation methods. */
31
22
  declare class ModelProjection<TEntity extends object, K extends keyof TEntity & string> {
32
23
  private readonly load;
@@ -0,0 +1,31 @@
1
+ import type BaseRepository from "./baseRepository";
2
+ import type { AnyRelationQuery } from "./relationQuery";
3
+ /** Private nested relation loading: preserves concrete owners and absent morph targets. */
4
+ type RelationNameInput = string | readonly string[];
5
+ declare function flattenRelationNames(relations: ReadonlyArray<RelationNameInput>): string[];
6
+ declare function isLoadableModel(value: unknown): value is {
7
+ load: (...names: string[]) => Promise<unknown>;
8
+ loaded: (name: string) => unknown;
9
+ constructor: object;
10
+ getRepository: () => BaseRepository<Record<string, unknown>, "id">;
11
+ toObject: () => object;
12
+ setLoaded: (name: string, value: unknown) => unknown;
13
+ };
14
+ declare function eagerLoadOnModels(models: Array<{
15
+ loaded: (name: string) => unknown;
16
+ constructor: object;
17
+ getRepository: () => BaseRepository<Record<string, unknown>, "id">;
18
+ toObject: () => object;
19
+ setLoaded: (name: string, value: unknown) => unknown;
20
+ load: (...names: string[]) => Promise<unknown>;
21
+ }>, paths: string[], knownAbsentMorphRoots?: ReadonlyMap<object, ReadonlySet<string>>, preparedRoots?: ReadonlyMap<object, ReadonlyMap<string, AnyRelationQuery>>): Promise<void>;
22
+ declare function loadNested(model: {
23
+ load: (...names: string[]) => Promise<unknown>;
24
+ loaded: (name: string) => unknown;
25
+ constructor: object;
26
+ getRepository: () => BaseRepository<Record<string, unknown>, "id">;
27
+ toObject: () => object;
28
+ setLoaded: (name: string, value: unknown) => unknown;
29
+ }, path: string, preparedRoot?: AnyRelationQuery): Promise<void>;
30
+ export type { RelationNameInput };
31
+ export { eagerLoadOnModels, flattenRelationNames, isLoadableModel, loadNested };
@@ -1,7 +1,7 @@
1
+ import { createMysqlPool, type MysqlExecutable, type MysqlPool, type MysqlPoolConnection } from "#strata-mysql-native";
1
2
  import { type ActiveDatabaseHandle } from "./connectionContext.ts";
2
3
  import type { DatabaseConnection } from "./connectionContracts.ts";
3
4
  import { type ReadOnlyObservationOptions } from "./isolatedReadOnlyObservation.ts";
4
- import { createMysqlPool, type MysqlExecutable, type MysqlPool, type MysqlPoolConnection, resetMysqlLoaderForTests } from "./mysqlNative";
5
5
  type MysqlConnection = ActiveDatabaseHandle & {
6
6
  begin<T>(callback: (transaction: ActiveDatabaseHandle) => Promise<T>): Promise<T>;
7
7
  close(): Promise<void>;
@@ -10,4 +10,4 @@ type MysqlConnection = ActiveDatabaseHandle & {
10
10
  declare function createMysqlConnectionFromPool(pool: MysqlExecutable): MysqlConnection;
11
11
  declare function createMysqlConnection(url: string): MysqlConnection;
12
12
  export type { MysqlConnection, MysqlExecutable, MysqlPool, MysqlPoolConnection };
13
- export { createMysqlConnection, createMysqlConnectionFromPool, createMysqlPool, resetMysqlLoaderForTests, };
13
+ export { createMysqlConnection, createMysqlConnectionFromPool, createMysqlPool };
@@ -2,6 +2,8 @@ type MysqlPromiseModule = {
2
2
  createPool: (config: {
3
3
  uri: string;
4
4
  timezone: string;
5
+ supportBigNumbers: true;
6
+ bigNumberStrings: false;
5
7
  connectionLimit?: number;
6
8
  }) => MysqlPool;
7
9
  };
@@ -1,4 +1,4 @@
1
1
  /** Canonical ORM classes and private construction accessors; package-private entry. */
2
2
  export { default as BaseRepository, getRepositoryBinding } from "./baseRepository";
3
- export { BelongsToManyRelationQuery, BelongsToRelationQuery, BoundModelFacade, createBoundModel, getModelBinding, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, Model, ModelQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, modelFacade, runObservers, } from "./model";
3
+ export { BelongsToManyRelationQuery, BelongsToRelationQuery, BoundModelFacade, createBoundModel, createModel, getModelBinding, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, Model, ModelQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, modelFacade, runObservers, } from "./model";
4
4
  export { RepositoryQuery, snapshotRepositoryQuery } from "./repositoryQuery";
@@ -1,5 +1,5 @@
1
+ import { type MysqlPoolConnection } from "#strata-mysql-native";
1
2
  import type { DisposeAck, MysqlDatabaseOptions, RawPin, RawPool } from "./driverPorts";
2
- import { type MysqlPoolConnection } from "./mysqlNative";
3
3
  /** mysql2 destroy() only calls stream.end(); its void return is not socket closure. */
4
4
  declare function destroyMysqlConnection(connection: MysqlPoolConnection): Promise<DisposeAck>;
5
5
  declare function createMysqlPin(connection: MysqlPoolConnection): RawPin;