@cosmicdrift/kumiko-framework 0.404.1 → 0.406.0

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 (52) hide show
  1. package/agents/api/framework-engine.md +3 -0
  2. package/agents/examples/lane-routing.md +13 -0
  3. package/dist/api/auth-routes-mfa.js +2 -2
  4. package/dist/api/index.d.ts +2 -2
  5. package/dist/api/index.js +1 -1
  6. package/dist/api/readiness.d.ts +0 -11
  7. package/dist/api/readiness.js +1 -30
  8. package/dist/crypto/index.d.ts +1 -0
  9. package/dist/crypto/index.js +1 -0
  10. package/dist/crypto/opaque-token-hash.d.ts +3 -0
  11. package/dist/crypto/opaque-token-hash.js +14 -0
  12. package/dist/crypto/subject-resolver.js +3 -8
  13. package/dist/db/blind-index-cleanup.js +3 -10
  14. package/dist/db/query.js +3 -18
  15. package/dist/derivatives/variant-key.d.ts +4 -0
  16. package/dist/derivatives/variant-key.js +4 -3
  17. package/dist/engine/boot-validator/field-conditions.js +2 -7
  18. package/dist/engine/boot-validator/list-table-aggregate-query.js +1 -1
  19. package/dist/engine/boot-validator/parent-ref.d.ts +0 -2
  20. package/dist/engine/boot-validator/parent-ref.js +1 -8
  21. package/dist/engine/boot-validator/projection-list-screens.js +1 -1
  22. package/dist/engine/boot-validator/read-gate.js +1 -1
  23. package/dist/engine/extensions/tenant-resource.d.ts +1 -0
  24. package/dist/engine/feature-config-events-jobs.js +7 -0
  25. package/dist/engine/find-entity.d.ts +3 -0
  26. package/dist/engine/find-entity.js +8 -0
  27. package/dist/engine/project-app-schema-for-roles.js +19 -55
  28. package/dist/files/file-handle.js +3 -16
  29. package/dist/jobs/job-runner-schedulers.d.ts +2 -2
  30. package/dist/jobs/job-runner-schedulers.js +8 -4
  31. package/dist/jobs/job-runner.js +7 -4
  32. package/dist/observability/ids.js +1 -8
  33. package/dist/pipeline/projection-rebuild.js +3 -17
  34. package/dist/pipeline/tenant-timezone-cache.js +8 -27
  35. package/dist/search/index.d.ts +3 -0
  36. package/dist/search/index.js +3 -0
  37. package/dist/search/is-entity-searchable.d.ts +2 -0
  38. package/dist/search/is-entity-searchable.js +4 -0
  39. package/dist/search/reindex-tenants-search.d.ts +19 -0
  40. package/dist/search/reindex-tenants-search.js +69 -0
  41. package/dist/utils/chunk.d.ts +1 -0
  42. package/dist/utils/chunk.js +7 -0
  43. package/dist/utils/hex.d.ts +3 -0
  44. package/dist/utils/hex.js +11 -0
  45. package/dist/utils/index.d.ts +3 -0
  46. package/dist/utils/index.js +3 -0
  47. package/dist/utils/lru-cache.d.ts +17 -0
  48. package/dist/utils/lru-cache.js +56 -0
  49. package/dist/utils/run-with-timeout.d.ts +11 -0
  50. package/dist/utils/run-with-timeout.js +30 -0
  51. package/package.json +4 -4
  52. package/src/changes.json +48 -0
@@ -970,9 +970,11 @@ type JobTrigger =
970
970
  | {
971
971
  cron: string;
972
972
  tz?: string;
973
+ wakesSleepingApp?: false;
973
974
  }
974
975
  | {
975
976
  maintenance: true;
977
+ wakesSleepingApp?: false;
976
978
  }
977
979
  | {
978
980
  manual: true;
@@ -1649,6 +1651,7 @@ type TenantDestroyHookResult =
1649
1651
  | {
1650
1652
  done: false;
1651
1653
  processed: number;
1654
+ pending?: boolean;
1652
1655
  }
1653
1656
  ;
1654
1657
  type TenantId = string;
@@ -14,6 +14,7 @@ Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
14
14
 
15
15
  - `r.job({ runIn: "worker" })` after an HTTP write
16
16
  - `trigger: { maintenance: true }` for a daily housekeeping job in the app's maintenance window (`KUMIKO_MAINTENANCE_WINDOW`)
17
+ - `wakesSleepingApp: false` on a cron trigger for upkeep that must not wake a sleeping shared app
17
18
  - End-to-end verification via `createAllInOneEntrypoint`
18
19
 
19
20
  ## Source
@@ -145,6 +146,10 @@ describe("lane-routing sample", () => {
145
146
  expect(registry.getJob("orders:job:prune-old-receipts")?.trigger).toEqual({
146
147
  maintenance: true,
147
148
  });
149
+ expect(registry.getJob("orders:job:warm-receipt-cache")?.trigger).toEqual({
150
+ cron: "*/15 * * * *",
151
+ wakesSleepingApp: false,
152
+ });
148
153
  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
149
154
  const entry = createAllInOneEntrypoint({
150
155
  rowLevelSecurity: "off",
@@ -279,6 +284,14 @@ export function createLaneRoutingFeature(): FeatureDefinition {
279
284
  r.job("prune-old-receipts", { trigger: { maintenance: true }, runIn: "worker" }, async () => {
280
285
  pruneRuns.push(Date.now());
281
286
  });
287
+
288
+ // Optional upkeep: `wakesSleepingApp: false` keeps a sleeping shared app asleep when a run is
289
+ // due; the run happens on the next wake instead.
290
+ r.job(
291
+ "warm-receipt-cache",
292
+ { trigger: { cron: "*/15 * * * *", wakesSleepingApp: false }, runIn: "worker" },
293
+ async () => {},
294
+ );
282
295
  });
283
296
  }
284
297
  ```
@@ -1,5 +1,5 @@
1
- import { createHash } from "node:crypto";
2
1
  import * as z from "zod";
2
+ import { hashOpaqueTokenSync } from "../crypto/opaque-token-hash.js";
3
3
  import { createAnonymousUser } from "../engine/system-user.js";
4
4
  import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
5
5
  import { Routes } from "./api-constants.js";
@@ -36,7 +36,7 @@ const MfaPreauthConfirmBody = z.object({
36
36
  // login.write.ts), so hashing it into a bucket key still caps the replay
37
37
  // even when the IP-based bucket is bypassed via header rotation.
38
38
  function preauthTokenKeyOf(token) {
39
- return `preauth-token:${createHash("sha256").update(token).digest("hex")}`;
39
+ return `preauth-token:${hashOpaqueTokenSync(token)}`;
40
40
  }
41
41
  export function registerMfaVerifyRoute(ctx) {
42
42
  const { api, dispatcher, config, getClientIp, mintSessionAndRespond, landingPathFragment } = ctx;
@@ -1,4 +1,6 @@
1
1
  export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.ts";
2
+ export type { TimedRunResult } from "../utils/run-with-timeout.ts";
3
+ export { runWithTimeout } from "../utils/run-with-timeout.ts";
2
4
  export { setTenantCookie } from "./anonymous-cookie.ts";
3
5
  export { collectAnonymousLiveEntities } from "./anonymous-live-entities.ts";
4
6
  export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.ts";
@@ -16,8 +18,6 @@ export type { JwtHelper } from "./jwt.ts";
16
18
  export { loadJwtSecretOrKeyring } from "./jwt.ts";
17
19
  export { publicOriginOf } from "./origin-middleware.ts";
18
20
  export type { PostAuthLandingArgs, PostAuthLandingResolver, } from "./post-auth-landing.ts";
19
- export type { TimedRunResult } from "./readiness.ts";
20
- export { runWithTimeout } from "./readiness.ts";
21
21
  export type { RedisSseBroker } from "./redis-sse-broker.ts";
22
22
  export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
23
23
  export { readonlyRequestContext as requestContext } from "./request-context-scopes.ts";
package/dist/api/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.js";
2
+ export { runWithTimeout } from "../utils/run-with-timeout.js";
2
3
  export { setTenantCookie } from "./anonymous-cookie.js";
3
4
  export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
4
5
  export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";
@@ -9,7 +10,6 @@ export { ExtraRouteRejection, signatureRoute } from "./extra-route.js";
9
10
  export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, } from "./http-cache.js";
10
11
  export { loadJwtSecretOrKeyring } from "./jwt.js";
11
12
  export { publicOriginOf } from "./origin-middleware.js";
12
- export { runWithTimeout } from "./readiness.js";
13
13
  export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
14
14
  export { readonlyRequestContext as requestContext } from "./request-context-scopes.js";
15
15
  export { buildRequestContextDataFromRequest } from "./request-id-middleware.js";
@@ -18,17 +18,6 @@ export type ReadinessProbeOptions = {
18
18
  readonly timeoutMs?: number;
19
19
  };
20
20
  export declare function createReadinessProbe(checks: readonly ReadinessCheck[], opts?: ReadinessProbeOptions): () => Promise<ReadinessResult>;
21
- export type TimedRunResult<T> = {
22
- readonly ok: true;
23
- readonly value: T;
24
- readonly latencyMs: number;
25
- } | {
26
- readonly ok: false;
27
- readonly error: unknown;
28
- readonly timedOut: boolean;
29
- readonly latencyMs: number;
30
- };
31
- export declare function runWithTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<TimedRunResult<T>>;
32
21
  export declare function dbPingCheck(db: DbConnection): ReadinessCheck;
33
22
  export declare function redisPingCheck(redis: Redis): ReadinessCheck;
34
23
  export declare function dispatcherLagCheck(db: DbConnection, consumerNames: readonly string[], maxLagEvents: bigint): ReadinessCheck;
@@ -12,6 +12,7 @@
12
12
  // so total latency must stay ≈ slowest check, not sum.
13
13
  import { pingDatabase } from "../db/queries/raw-sql.js";
14
14
  import { getAllConsumerProgress } from "../pipeline/event-dispatcher.js";
15
+ import { runWithTimeout } from "../utils/run-with-timeout.js";
15
16
  const DEFAULT_TIMEOUT_MS = 2_000;
16
17
  export function createReadinessProbe(checks, opts = {}) {
17
18
  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -23,36 +24,6 @@ export function createReadinessProbe(checks, opts = {}) {
23
24
  };
24
25
  };
25
26
  }
26
- class TimeoutError extends Error {
27
- }
28
- export async function runWithTimeout(run, timeoutMs) {
29
- const start = performance.now();
30
- const elapsedMs = () => Math.round(performance.now() - start);
31
- let timer;
32
- try {
33
- const value = await Promise.race([
34
- run(),
35
- new Promise((_, reject) => {
36
- timer = setTimeout(() => reject(new TimeoutError(`timeout after ${timeoutMs}ms`)), timeoutMs);
37
- // Don't keep the event loop alive on a hung probe during shutdown.
38
- timer.unref?.();
39
- }),
40
- ]);
41
- return { ok: true, value, latencyMs: elapsedMs() };
42
- }
43
- catch (error) {
44
- return {
45
- ok: false,
46
- error,
47
- timedOut: error instanceof TimeoutError,
48
- latencyMs: elapsedMs(),
49
- };
50
- }
51
- finally {
52
- if (timer)
53
- clearTimeout(timer);
54
- }
55
- }
56
27
  async function runOne(check, timeoutMs) {
57
28
  const result = await runWithTimeout(check.run, timeoutMs);
58
29
  if (result.ok)
@@ -6,6 +6,7 @@ export { resolvePlatformKeks } from "./kek-source.ts";
6
6
  export { KeyAlreadyExistsError, KeyErasedError, type KmsAdapter, type KmsContext, type LocalKeyKmsAdapter, type SubjectId, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForUser, } from "./kms-adapter.ts";
7
7
  export { ENCRYPTION_UNAVAILABLE_CODE, EncryptionUnavailableError } from "./kms-outage.ts";
8
8
  export { type KmsWiring, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.ts";
9
+ export { hashOpaqueToken, hashOpaqueTokenSync, opaqueTokenHashMatches, } from "./opaque-token-hash.ts";
9
10
  export { createPgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.ts";
10
11
  export { PII_CIPHERTEXT_CORRUPT_CODE, PiiCiphertextCorruptError, } from "./pii-ciphertext-corrupt.ts";
11
12
  export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.ts";
@@ -6,6 +6,7 @@ export { resolvePlatformKeks } from "./kek-source.js";
6
6
  export { KeyAlreadyExistsError, KeyErasedError, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForUser, } from "./kms-adapter.js";
7
7
  export { ENCRYPTION_UNAVAILABLE_CODE, EncryptionUnavailableError } from "./kms-outage.js";
8
8
  export { requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
9
+ export { hashOpaqueToken, hashOpaqueTokenSync, opaqueTokenHashMatches, } from "./opaque-token-hash.js";
9
10
  export { createPgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
10
11
  export { PII_CIPHERTEXT_CORRUPT_CODE, PiiCiphertextCorruptError, } from "./pii-ciphertext-corrupt.js";
11
12
  export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
@@ -0,0 +1,3 @@
1
+ export declare function hashOpaqueToken(token: string): Promise<string>;
2
+ export declare function hashOpaqueTokenSync(token: string): string;
3
+ export declare function opaqueTokenHashMatches(token: string, storedHash: string): boolean;
@@ -0,0 +1,14 @@
1
+ import { createHash, timingSafeEqual } from "node:crypto";
2
+ import { digestHex } from "../utils/hex.js";
3
+ export function hashOpaqueToken(token) {
4
+ return digestHex("SHA-256", token);
5
+ }
6
+ export function hashOpaqueTokenSync(token) {
7
+ return createHash("sha256").update(token).digest("hex");
8
+ }
9
+ export function opaqueTokenHashMatches(token, storedHash) {
10
+ const actual = Buffer.from(hashOpaqueTokenSync(token));
11
+ const expected = Buffer.from(storedHash);
12
+ // timingSafeEqual throws on a length mismatch, and the throw itself is a timing signal.
13
+ return actual.length === expected.length && timingSafeEqual(actual, expected);
14
+ }
@@ -1,4 +1,5 @@
1
1
  import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
2
+ import { isFileField } from "../engine/field-helpers.js";
2
3
  import { isSelfPiiField } from "./is-self-pii-field.js";
3
4
  import { RECORD_ENTITY_PATTERN } from "./kms-adapter.js";
4
5
  // Thrown when a field IS pii-annotated but the row can't name its subject —
@@ -157,24 +158,18 @@ export function collectPiiSubjectFields(entity) {
157
158
  .filter(([, field]) => hasSubjectAnnotation(field))
158
159
  .map(([name]) => name);
159
160
  }
160
- function isFileReferenceField(field) {
161
- return (field.type === "file" ||
162
- field.type === "image" ||
163
- field.type === "files" ||
164
- field.type === "images");
165
- }
166
161
  // File columns hold only the fileRef uuid; the binary is erased by the file-ref
167
162
  // user-data hook, so these stay annotated (forget) but are never ciphertext.
168
163
  export function collectPiiEncryptedFields(entity) {
169
164
  return Object.entries(entity.fields)
170
- .filter(([, field]) => hasSubjectAnnotation(field) && !isFileReferenceField(field))
165
+ .filter(([, field]) => hasSubjectAnnotation(field) && !isFileField(field))
171
166
  .map(([name]) => name);
172
167
  }
173
168
  // The annotated file-reference fields: never ciphertext today, but events from the
174
169
  // old backfill (which encrypted them) still carry it and must replay.
175
170
  export function collectPiiFileReferenceFields(entity) {
176
171
  return Object.entries(entity.fields)
177
- .filter(([, field]) => hasSubjectAnnotation(field) && isFileReferenceField(field))
172
+ .filter(([, field]) => hasSubjectAnnotation(field) && isFileField(field))
178
173
  .map(([name]) => name);
179
174
  }
180
175
  /** Subject-annotated fields that may be plaintext in the derived search index. */
@@ -13,6 +13,7 @@
13
13
  import { collectLookupableFields } from "../crypto/blind-index.js";
14
14
  import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern.js";
15
15
  import { isSelfPiiField } from "../crypto/is-self-pii-field.js";
16
+ import { findEntity } from "../engine/find-entity.js";
16
17
  import { toSnakeCase } from "../utils/case.js";
17
18
  import { resolveTableName } from "./entity-table-meta.js";
18
19
  import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
@@ -115,14 +116,6 @@ export async function subjectRowExistsInTenant(db, features, subjectId, tenantId
115
116
  return false;
116
117
  });
117
118
  }
118
- function findEntityByExactName(features, entityName) {
119
- for (const feature of features.values()) {
120
- const entity = feature.entities?.[entityName];
121
- if (entity)
122
- return entity;
123
- }
124
- return undefined;
125
- }
126
119
  // Tighter than subjectRowExistsInTenant: the record subject names its own
127
120
  // entity, so this is a single-table lookup instead of a self-PII scan
128
121
  // across the whole registry.
@@ -132,7 +125,7 @@ function findEntityByExactName(features, entityName) {
132
125
  // at create) — a composite PK or shared table would break this.
133
126
  export async function recordRowExistsInTenant(db, features, entityName, recordId, tenantId) {
134
127
  return runInSystemRowLevelSecurityScope("record existence check spans tenants", async () => {
135
- const entity = findEntityByExactName(features, entityName);
128
+ const entity = findEntity(features, entityName);
136
129
  if (!entity)
137
130
  return false;
138
131
  const tableName = resolveTableName(entityName, entity, undefined);
@@ -159,7 +152,7 @@ export async function recordEventsOwnedExclusivelyByTenant(db, aggregateType, ag
159
152
  // tenant-scoped policy for the row's real owner (not the acting user's tenant).
160
153
  export async function recordRowOwningTenantId(db, features, entityName, recordId) {
161
154
  return runInSystemRowLevelSecurityScope("record owner lookup spans tenants", async () => {
162
- const entity = findEntityByExactName(features, entityName);
155
+ const entity = findEntity(features, entityName);
163
156
  if (!entity)
164
157
  return undefined;
165
158
  const tableName = resolveTableName(entityName, entity, undefined);
package/dist/db/query.js CHANGED
@@ -391,26 +391,11 @@ export async function insertOne(db, table, values) {
391
391
  if (managedDenied)
392
392
  throw managedDenied;
393
393
  const info = extractTableInfo(table);
394
- const entries = Object.entries(values)
395
- .filter(([k]) => info.hasColumn(k))
396
- .map(([k, v]) => {
397
- const col = info.columnOf(k);
398
- const pgType = info.pgTypeOf(col);
399
- return { col, prepared: prepareValue(v, pgType) };
400
- });
394
+ const entries = insertEntries(info, values);
401
395
  if (entries.length === 0)
402
396
  throw new Error("insertOne: empty values object");
403
- const cols = entries.map((e) => quoteIdent(e.col)).join(", ");
404
- const params = [];
405
- const placeholders = entries
406
- .map((e) => {
407
- if (e.prepared.kind === "literal")
408
- return e.prepared.literal;
409
- params.push(e.prepared.bound);
410
- return `$${params.length}${e.prepared.sql}`;
411
- })
412
- .join(", ");
413
- const sqlText = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES (${placeholders}) RETURNING *`;
397
+ const { sqlPrefix, params } = buildInsertSql(info, entries);
398
+ const sqlText = `${sqlPrefix} RETURNING *`;
414
399
  const rows = await unsafeLoggingClosedConnection(db, sqlText, params, {
415
400
  operation: "insertOne",
416
401
  table: info.name,
@@ -4,6 +4,10 @@ export declare function specHash(spec: VariantSpec): string;
4
4
  export declare const VARIANT_NAME_PATTERN: RegExp;
5
5
  export declare function variantSuffix(name: string, spec: VariantSpec): string;
6
6
  export declare function isDerivativeSuffix(suffix: string): boolean;
7
+ export declare function splitKey(key: string): {
8
+ readonly base: string;
9
+ readonly ext: string;
10
+ };
7
11
  export declare function derivativeListPrefix(originalKey: string): string;
8
12
  export declare function isDerivativeKeyOf(originalKey: string, candidateKey: string): boolean;
9
13
  export declare function parseDerivativeKey(candidateKey: string): {
@@ -41,9 +41,10 @@ const DERIVATIVE_SUFFIX_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}-[0-9a-f]{16}$/
41
41
  export function isDerivativeSuffix(suffix) {
42
42
  return DERIVATIVE_SUFFIX_PATTERN.test(suffix);
43
43
  }
44
- // Mirrors deriveKey's own split so callers get the exact same base/ext this
45
- // key's derivatives were built from.
46
- function splitKey(key) {
44
+ // Splits on the last dot of the last path segment only, so `archive.v2/foo.jpg`
45
+ // yields base `archive.v2/foo`. No dot there: the whole key is the base, ext is
46
+ // empty. deriveKey uses the same split, so derivative keys line up with it.
47
+ export function splitKey(key) {
47
48
  const lastSlash = key.lastIndexOf("/");
48
49
  const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
49
50
  const lastDot = lastSegment.lastIndexOf(".");
@@ -1,5 +1,6 @@
1
1
  import { isFileSubField } from "../../files/file-field-slots.js";
2
2
  import { parseMaxSize } from "../../files/types.js";
3
+ import { isFileField } from "../field-helpers.js";
3
4
  import { conditionComparisonValues, LOCKABLE_FIELD_TYPES } from "./entity-handler.js";
4
5
  const STATE_KEYS = ["visibleWhen", "requiredWhen"];
5
6
  const SUB_CONDITION_TYPES = new Set([
@@ -178,15 +179,9 @@ function assertField(feature, entityName, entity, fieldName, field) {
178
179
  }
179
180
  if (field.type === "embedded")
180
181
  assertEmbeddedField(where, field);
181
- if (isFileAcceptField(field))
182
+ if (isFileField(field))
182
183
  assertAcceptEntries(where, field.accept);
183
184
  }
184
- function isFileAcceptField(field) {
185
- return (field.type === "file" ||
186
- field.type === "files" ||
187
- field.type === "image" ||
188
- field.type === "images");
189
- }
190
185
  export function validateFieldConditions(feature) {
191
186
  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
192
187
  for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -1,7 +1,7 @@
1
1
  import { resolveEntityBehindListQuery } from "../entity-list-searchability.js";
2
+ import { findEntity } from "../find-entity.js";
2
3
  import { normalizeListColumn } from "../screen-helpers.js";
3
4
  import { entityAggregateFieldLookup, validateListTableAggregateFieldTypes, } from "./list-table-aggregate-options.js";
4
- import { findEntity } from "./parent-ref.js";
5
5
  import { getZodObjectShape } from "./zod-shape.js";
6
6
  function columnValueTypeLookup(columns) {
7
7
  const valueTypes = new Map(columns
@@ -1,4 +1,2 @@
1
- import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
2
1
  import type { FeatureDefinition } from "../types/index.ts";
3
- export declare function findEntity(featureMap: ReadonlyMap<string, FeatureDefinition>, entityName: string): EntityDefinition | undefined;
4
2
  export declare function validateParentRefs(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
@@ -1,4 +1,5 @@
1
1
  import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
2
+ import { findEntity } from "../find-entity.js";
2
3
  // --- Parent-ref boot validation ---
3
4
  //
4
5
  // Join-row entities (EntityDefinition.parentRef) derive both the write-path
@@ -8,14 +9,6 @@ import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handler
8
9
  // was supplied — throwing there would 500 every custom handler and
9
10
  // framework-internal detail() call that doesn't wire it, so the enforcement
10
11
  // has to happen loudly here instead, once, at boot.
11
- export function findEntity(featureMap, entityName) {
12
- for (const f of featureMap.values()) {
13
- const entity = f.entities?.[entityName];
14
- if (entity)
15
- return entity;
16
- }
17
- return undefined;
18
- }
19
12
  function findQueryHandler(featureMap, handlerName) {
20
13
  for (const f of featureMap.values()) {
21
14
  const handler = f.queryHandlers[handlerName];
@@ -1,11 +1,11 @@
1
1
  import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
2
+ import { findEntity } from "../find-entity.js";
2
3
  import { QnTypes, qualifyEntityName } from "../qualified-name.js";
3
4
  import { isEditLayoutScreen } from "../screen-helpers.js";
4
5
  import { bootRuleError } from "./boot-rule.js";
5
6
  import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
6
7
  import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
7
8
  import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
8
- import { findEntity } from "./parent-ref.js";
9
9
  import { getZodObjectShape } from "./zod-shape.js";
10
10
  // Sibling to entity-list-screens.ts rather than an extension of it:
11
11
  // validateOneEntityListScreen is typed to EntityListScreenDefinition and
@@ -1,6 +1,6 @@
1
1
  import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { FILE_REF_ENTITY_NAME } from "../../files/types.js";
3
- import { findEntity } from "./parent-ref.js";
3
+ import { findEntity } from "../find-entity.js";
4
4
  function fail(check, message) {
5
5
  throw new Error(`[Kumiko ReadGate] entity "${check.entityName}" (feature: "${check.feature.name}"): ${message}`);
6
6
  }
@@ -7,6 +7,7 @@ export type TenantDestroyHookResult = {
7
7
  } | {
8
8
  readonly done: false;
9
9
  readonly processed: number;
10
+ readonly pending?: boolean;
10
11
  };
11
12
  export interface TenantResourceHookCtx {
12
13
  readonly tenantId: TenantId;
@@ -11,6 +11,13 @@ function assertScheduleTrigger(featureName, jobName, trigger) {
11
11
  throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { maintenance: ${JSON.stringify(trigger.maintenance)} } — ` +
12
12
  "the only valid value is true; the run time comes from KUMIKO_MAINTENANCE_WINDOW.");
13
13
  }
14
+ if ("wakesSleepingApp" in trigger && trigger.wakesSleepingApp !== undefined) {
15
+ const isScheduled = "cron" in trigger || "maintenance" in trigger;
16
+ if (!isScheduled || trigger.wakesSleepingApp !== false) {
17
+ throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { wakesSleepingApp: ${JSON.stringify(trigger.wakesSleepingApp)} } — ` +
18
+ "only false is valid, and only on a cron or maintenance trigger; leave it out to wake the app.");
19
+ }
20
+ }
14
21
  if ("cron" in trigger && trigger.tz !== undefined && !isValidIanaTimeZone(trigger.tz)) {
15
22
  throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { cron, tz: ${JSON.stringify(trigger.tz)} } — ` +
16
23
  'tz must be an IANA time zone name such as "Europe/Berlin".');
@@ -0,0 +1,3 @@
1
+ import type { EntityDefinition } from "./types/fields.ts";
2
+ import type { FeatureDefinition } from "./types/index.ts";
3
+ export declare function findEntity(features: ReadonlyMap<string, FeatureDefinition>, entityName: string): EntityDefinition | undefined;
@@ -0,0 +1,8 @@
1
+ export function findEntity(features, entityName) {
2
+ for (const feature of features.values()) {
3
+ const entity = feature.entities?.[entityName];
4
+ if (entity)
5
+ return entity;
6
+ }
7
+ return undefined;
8
+ }
@@ -255,62 +255,26 @@ function keepTreeAction(action, keptScreenQns) {
255
255
  return true; // target-based dispatch, not a screen navigate
256
256
  return keptScreenQns.has(action.screen);
257
257
  }
258
- // --- RowAction / ToolbarAction / RelatedListToolbarAction array projectors ---
259
- // Each returns the ORIGINAL array reference when nothing was filtered, and
260
- // `undefined` (never an empty array) when everything was — same JSON-safety
261
- // convention as buildAppSchema.
262
- function keepRowAction(action, feature, indices, keptScreenQns) {
258
+ function keepScreenTargetAction(action, feature, indices, keptScreenQns) {
263
259
  if (action.kind === "drawer")
264
260
  return isDrawerTargetKept(feature, action.screen, keptScreenQns);
265
261
  if (action.kind === "navigate")
266
262
  return isNavigateTargetKept(action, indices, keptScreenQns);
267
- return true; // writeHandler — no screen target
263
+ return true; // no screen target
268
264
  }
269
- function projectRowActionArray(actions, feature, indices, keptScreenQns) {
265
+ function filterKeptActions(actions, keep) {
270
266
  if (actions === undefined)
271
267
  return undefined;
272
- const kept = actions.filter((a) => keepRowAction(a, feature, indices, keptScreenQns));
268
+ const kept = actions.filter(keep);
273
269
  if (kept.length === actions.length)
274
270
  return actions;
275
271
  return kept.length > 0 ? kept : undefined;
276
272
  }
277
- function keepToolbarAction(action, feature, indices, keptScreenQns) {
278
- if (action.kind === "navigate")
279
- return isNavigateTargetKept(action, indices, keptScreenQns);
280
- if (action.kind === "drawer")
281
- return isDrawerTargetKept(feature, action.screen, keptScreenQns);
282
- return true;
283
- }
284
- function projectToolbarActionArray(actions, feature, indices, keptScreenQns) {
285
- if (actions === undefined)
286
- return undefined;
287
- const kept = actions.filter((a) => keepToolbarAction(a, feature, indices, keptScreenQns));
288
- if (kept.length === actions.length)
289
- return actions;
290
- return kept.length > 0 ? kept : undefined;
291
- }
292
- function keepRelatedListToolbarAction(action, feature, indices, keptScreenQns) {
293
- if (action.kind === "navigate")
294
- return isNavigateTargetKept(action, indices, keptScreenQns);
295
- if (action.kind === "drawer")
296
- return isDrawerTargetKept(feature, action.screen, keptScreenQns);
297
- return true;
298
- }
299
- function projectRelatedListToolbarActionArray(actions, feature, indices, keptScreenQns) {
300
- if (actions === undefined)
301
- return undefined;
302
- const kept = actions.filter((a) => keepRelatedListToolbarAction(a, feature, indices, keptScreenQns));
303
- if (kept.length === actions.length)
304
- return actions;
305
- return kept.length > 0 ? kept : undefined;
273
+ function projectActionArray(actions, feature, indices, keptScreenQns) {
274
+ return filterKeptActions(actions, (a) => keepScreenTargetAction(a, feature, indices, keptScreenQns));
306
275
  }
307
276
  function projectTreeActionArray(actions, keptScreenQns) {
308
- if (actions === undefined)
309
- return undefined;
310
- const kept = actions.filter((a) => keepTreeAction(a, keptScreenQns));
311
- if (kept.length === actions.length)
312
- return actions;
313
- return kept.length > 0 ? kept : undefined;
277
+ return filterKeptActions(actions, (a) => keepTreeAction(a, keptScreenQns));
314
278
  }
315
279
  function projectTreeAction(action, keptScreenQns) {
316
280
  if (action === undefined)
@@ -329,16 +293,16 @@ function projectEmptyState(emptyState, feature, indices, keptScreenQns) {
329
293
  return undefined;
330
294
  if (emptyState.action === undefined)
331
295
  return emptyState;
332
- if (keepRowAction(emptyState.action, feature, indices, keptScreenQns))
296
+ if (keepScreenTargetAction(emptyState.action, feature, indices, keptScreenQns))
333
297
  return emptyState;
334
298
  const { action, ...rest } = emptyState;
335
299
  return rest;
336
300
  }
337
301
  function projectRelatedListSection(section, feature, indices, keptScreenQns) {
338
302
  const { actions, rowActions, toolbarActions, rowClick, emptyState, ...rest } = section;
339
- const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
340
- const nextRowActions = projectRowActionArray(rowActions, feature, indices, keptScreenQns);
341
- const nextToolbarActions = projectRelatedListToolbarActionArray(toolbarActions, feature, indices, keptScreenQns);
303
+ const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
304
+ const nextRowActions = projectActionArray(rowActions, feature, indices, keptScreenQns);
305
+ const nextToolbarActions = projectActionArray(toolbarActions, feature, indices, keptScreenQns);
342
306
  const nextRowClick = rowClick === undefined || isRowClickEntityKept(rowClick.entity, indices, keptScreenQns)
343
307
  ? rowClick
344
308
  : undefined;
@@ -365,18 +329,18 @@ function projectEditSection(section, feature, indices, keptScreenQns) {
365
329
  return projectRelatedListSection(section, feature, indices, keptScreenQns);
366
330
  case "extension": {
367
331
  const { actions, ...rest } = section;
368
- const kept = projectRowActionArray(actions, feature, indices, keptScreenQns);
332
+ const kept = projectActionArray(actions, feature, indices, keptScreenQns);
369
333
  return kept === actions ? section : { ...rest, ...(kept !== undefined && { actions: kept }) };
370
334
  }
371
335
  case "writeForm": {
372
336
  const { actions, ...rest } = section;
373
- const kept = projectRowActionArray(actions, feature, indices, keptScreenQns);
337
+ const kept = projectActionArray(actions, feature, indices, keptScreenQns);
374
338
  return kept === actions ? section : { ...rest, ...(kept !== undefined && { actions: kept }) };
375
339
  }
376
340
  default: {
377
341
  // kind undefined or "fields"
378
342
  const { actions, ...rest } = section;
379
- const kept = projectRowActionArray(actions, feature, indices, keptScreenQns);
343
+ const kept = projectActionArray(actions, feature, indices, keptScreenQns);
380
344
  return kept === actions ? section : { ...rest, ...(kept !== undefined && { actions: kept }) };
381
345
  }
382
346
  }
@@ -471,8 +435,8 @@ function dropUnreachableCreateScreen(screen, feature, keptScreenQns) {
471
435
  function projectListScreen(original, feature, indices, keptScreenQns) {
472
436
  const screen = dropUnreachableCreateScreen(original, feature, keptScreenQns);
473
437
  const { rowActions, toolbarActions, ...rest } = screen;
474
- const nextRowActions = projectRowActionArray(rowActions, feature, indices, keptScreenQns);
475
- const nextToolbarActions = projectToolbarActionArray(toolbarActions, feature, indices, keptScreenQns);
438
+ const nextRowActions = projectActionArray(rowActions, feature, indices, keptScreenQns);
439
+ const nextToolbarActions = projectActionArray(toolbarActions, feature, indices, keptScreenQns);
476
440
  const expandableRow = screen.type === "entityList" ? screen.expandableRow : undefined;
477
441
  const nextExpandableRow = expandableRow === undefined
478
442
  ? undefined
@@ -493,7 +457,7 @@ function projectProjectionDetailScreen(screen, feature, indices, keptScreenQns)
493
457
  const { metrics, header, actions, layout, listScreenId, ...rest } = screen;
494
458
  const nextMetrics = projectMetrics(metrics, indices, keptScreenQns);
495
459
  const nextHeader = projectHeader(header, indices, keptScreenQns);
496
- const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
460
+ const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
497
461
  const nextLayout = projectEditLayout(layout, feature, indices, keptScreenQns);
498
462
  const nextListScreenId = projectListScreenId(listScreenId, indices, keptScreenQns);
499
463
  const unchanged = nextMetrics === metrics &&
@@ -515,7 +479,7 @@ function projectProjectionDetailScreen(screen, feature, indices, keptScreenQns)
515
479
  function projectEntityEditScreen(screen, feature, indices, keptScreenQns) {
516
480
  const { redirect, actions, layout, listScreenId, ...rest } = screen;
517
481
  const nextRedirect = projectRedirect(feature.featureName, redirect, keptScreenQns);
518
- const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
482
+ const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
519
483
  const nextLayout = projectEditLayout(layout, feature, indices, keptScreenQns);
520
484
  const nextListScreenId = projectListScreenId(listScreenId, indices, keptScreenQns);
521
485
  const unchanged = nextRedirect === redirect &&
@@ -592,7 +556,7 @@ function projectScreen(screen, feature, indices, keptScreenQns) {
592
556
  case "dashboard": {
593
557
  const { actions, ...rest } = screen;
594
558
  const nextPanels = projectDashboardPanels(screen.panels, feature, keptScreenQns);
595
- const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
559
+ const nextActions = projectActionArray(actions, feature, indices, keptScreenQns);
596
560
  if (nextPanels === screen.panels && nextActions === actions)
597
561
  return screen;
598
562
  return {