@cosmicdrift/kumiko-framework 0.414.0 → 0.415.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 (68) hide show
  1. package/agents/api/framework-engine.md +9 -3
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +10 -1
  4. package/agents/api/renderer-web.md +20 -3
  5. package/agents/api/types.md +47 -14
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +7 -5
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/record-detail-layout.md +113 -7
  10. package/agents/widgets.md +7 -0
  11. package/dist/api/request-context-internals.d.ts +2 -0
  12. package/dist/api/request-context-scopes.js +9 -2
  13. package/dist/api/request-context.js +1 -1
  14. package/dist/api/routes.js +4 -4
  15. package/dist/api/server-event-dispatcher.js +3 -0
  16. package/dist/db/parent-ref-clause.js +31 -3
  17. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  18. package/dist/db/parent-ref-global-hosts.js +50 -12
  19. package/dist/db/queries/rls-boot-catalog.js +5 -6
  20. package/dist/db/queries/rls-shape.d.ts +1 -0
  21. package/dist/db/queries/rls-shape.js +21 -6
  22. package/dist/engine/boot-validator/boot-rules.d.ts +16 -6
  23. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  24. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  25. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  26. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  27. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +2 -2
  28. package/dist/engine/boot-validator/list-row-guidance-rules.js +2 -2
  29. package/dist/engine/boot-validator/list-row-guidance.js +15 -1
  30. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  31. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  32. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  33. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  34. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  35. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  36. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  37. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  38. package/dist/engine/boot-validator/query-refs.js +10 -0
  39. package/dist/engine/boot-validator/screens-actions.js +1 -1
  40. package/dist/engine/named-filter-roles.js +6 -14
  41. package/dist/engine/schema-builder.js +3 -1
  42. package/dist/engine/soft-delete-cleanup.js +2 -0
  43. package/dist/errors/reasons.d.ts +1 -0
  44. package/dist/errors/reasons.js +4 -0
  45. package/dist/i18n/required-surface-keys.js +2 -1
  46. package/dist/jobs/job-runner-execution.js +3 -0
  47. package/dist/jobs/job-runner-types.d.ts +1 -0
  48. package/dist/jobs/job-runner.js +8 -0
  49. package/dist/pipeline/context-services.d.ts +1 -1
  50. package/dist/pipeline/context-services.js +1 -1
  51. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  52. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  53. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  54. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  55. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  56. package/dist/search/meilisearch-adapter-internals.js +5 -0
  57. package/dist/search/meilisearch-adapter.d.ts +1 -0
  58. package/dist/search/meilisearch-adapter.js +3 -2
  59. package/dist/ui-types/card-column-roles.d.ts +2 -0
  60. package/dist/ui-types/card-column-roles.js +15 -0
  61. package/dist/ui-types/index.d.ts +2 -2
  62. package/dist/ui-types/index.js +1 -1
  63. package/package.json +3 -3
  64. package/presets/biome-plugins/no-date-api.grit +3 -1
  65. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  66. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  67. package/presets/biome-rules.json +12 -10
  68. package/src/changes.json +57 -0
@@ -48,6 +48,7 @@ export type JobRunner = {
48
48
  handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
49
49
  attachDispatcher(ref: DispatchWriteRef): void;
50
50
  countPendingJobs(): Promise<number>;
51
+ isJobPending?(jobName: string, jobId: string): Promise<boolean>;
51
52
  };
52
53
  export type JobRunnerOptions = {
53
54
  registry: Registry;
@@ -571,6 +571,14 @@ export function createJobRunner(options) {
571
571
  attachDispatcher(ref) {
572
572
  dispatchWriteRef = ref;
573
573
  },
574
+ async isJobPending(jobName, jobId) {
575
+ const jobDef = allJobs.get(jobName);
576
+ if (!jobDef) {
577
+ throw new Error(`Unknown job: ${jobName}`);
578
+ }
579
+ const state = await queues[laneForJob(jobDef)].getJobState(jobId);
580
+ return state !== "completed" && state !== "failed" && state !== "unknown";
581
+ },
574
582
  async countPendingJobs() {
575
583
  let total = 0;
576
584
  for (const queue of Object.values(queues)) {
@@ -20,7 +20,7 @@ export declare const APP_CONTEXT_KEY_ROLES: {
20
20
  readonly _notifyFactory: "service";
21
21
  readonly _notifyInTransactionFactory: "service";
22
22
  readonly _notifyAfterCommitFactory: "service";
23
- readonly _deliveryAttemptLogFactory: "service";
23
+ readonly _deliveryAttemptLogFactory: "wiring";
24
24
  readonly _logOwnDeliveryAttempt: "service";
25
25
  readonly _escapeHatchAuditSink: "service";
26
26
  readonly db: "wiring";
@@ -20,7 +20,7 @@ export const APP_CONTEXT_KEY_ROLES = {
20
20
  _notifyFactory: "service",
21
21
  _notifyInTransactionFactory: "service",
22
22
  _notifyAfterCommitFactory: "service",
23
- _deliveryAttemptLogFactory: "service",
23
+ _deliveryAttemptLogFactory: "wiring",
24
24
  _logOwnDeliveryAttempt: "service",
25
25
  _escapeHatchAuditSink: "service",
26
26
  db: "wiring",
@@ -350,6 +350,9 @@ function buildConsumerRequestScope(consumer, causationSource) {
350
350
  handler: consumer.name,
351
351
  feature: consumer.featureName ?? qnScope(consumer.name),
352
352
  writeOrigin,
353
+ ...(consumer.irreversibleWithoutEntryHandler && {
354
+ irreversibleWithoutEntryHandler: consumer.irreversibleWithoutEntryHandler,
355
+ }),
353
356
  };
354
357
  }
355
358
  async function applyEvent(consumer, row, context) {
@@ -1,3 +1,4 @@
1
+ import type { IrreversibleWithoutEntryHandler } from "@cosmicdrift/kumiko-types/config";
1
2
  import type { Meter, Tracer } from "@cosmicdrift/kumiko-types/observability";
2
3
  import type { PgListenClient } from "../db/connection.ts";
3
4
  import type { AppContext } from "../engine/types/index.ts";
@@ -22,6 +23,7 @@ export type EventConsumer = {
22
23
  readonly featureName?: string;
23
24
  readonly delivery?: "shared" | "per-instance";
24
25
  readonly startFrom?: "beginning" | "now";
26
+ readonly irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
25
27
  };
26
28
  export type DispatcherPassResult = {
27
29
  readonly processed: number;
@@ -87,7 +87,7 @@ export function denyTransactionBoundSurfaces(handlerContext) {
87
87
  // A notify factory builds a working notify, so a phase that denies ctx.notify must drop them too,
88
88
  // along with the delivery attempt log that belongs to a delivery.
89
89
  export function withoutNotifyFactories(services) {
90
- const { _notifyFactory: _factory, _notifyInTransactionFactory: _inTransaction, _notifyAfterCommitFactory: _afterCommit, _deliveryAttemptLogFactory: _attemptLogFactory, _logOwnDeliveryAttempt: _ownAttemptLog, ...rest } = services;
90
+ const { _notifyFactory: _factory, _notifyInTransactionFactory: _inTransaction, _notifyAfterCommitFactory: _afterCommit, _logOwnDeliveryAttempt: _ownAttemptLog, ...rest } = services;
91
91
  return rest;
92
92
  }
93
93
  // The beforeTransaction phase has no write need at all, so it also loses the outside-transaction
@@ -1,3 +1,4 @@
1
+ import { IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES } from "@cosmicdrift/kumiko-types/config";
1
2
  import { requestContext } from "../api/request-context.js";
2
3
  import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
3
4
  // forget hard-purges regardless of softDelete; delete is only irreversible
@@ -6,17 +7,33 @@ export function isIrreversibleEntityVerb(verb, entity) {
6
7
  return verb === "forget" || !entity.softDelete;
7
8
  }
8
9
  // The gate reads the directly dispatched entry handler; a write dispatched inside a deferred
9
- // context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. Direct
10
- // executor/KMS calls without one stay ungated in exactly three cases: deleting derived data
11
- // rebuildable from a reversible source (document-ingest-foundation's forget-extract-with-file-ref
12
- // consumer, re-created on fileRef.restored), pipelines started by a risk "high" handler or a
13
- // cron scan (forget cleanup, retention, tenant destroy), and the step-dispatcher erasing the
14
- // per-dispatch record key once the outcome is recorded. A deferred context can't return the
15
- // reason to the agent synchronously, so the gate sits at the primitives.
10
+ // context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. A direct
11
+ // executor/KMS call inside a request scope without one passes only when the job or consumer
12
+ // declared irreversibleWithoutEntryHandler, whose closed union names the allowed cases. Without any
13
+ // request scope (boot seed, CLI, direct test call) nothing is checked. A deferred context can't
14
+ // return the reason to the agent synchronously, so the gate sits at the primitives.
16
15
  function assertEntryHandlerHighRisk(args) {
17
- const entryHandler = requestContext.get()?.entryHandler;
18
- // skip: no entry handler (see above) or the entry handler already resolves "high".
19
- if (!entryHandler || entryHandler.risk === "high")
16
+ const scope = requestContext.get();
17
+ // skip: no request scope, so no pipeline to hold to the gate.
18
+ if (!scope)
19
+ return;
20
+ const { entryHandler } = scope;
21
+ if (!entryHandler) {
22
+ // skip: the job or consumer declared why it may run without an entry handler.
23
+ if (scope.irreversibleWithoutEntryHandler)
24
+ return;
25
+ throw new AccessDeniedError({
26
+ message: undeclaredPipelineMessage(scope.handler, args.operation),
27
+ details: {
28
+ reason: FrameworkReasons.irreversibleOperationWithoutEntryHandler,
29
+ handler: scope.handler,
30
+ gate: args.reason,
31
+ ...args.details,
32
+ },
33
+ });
34
+ }
35
+ // skip: the entry handler already resolves "high".
36
+ if (entryHandler.risk === "high")
20
37
  return;
21
38
  throw new AccessDeniedError({
22
39
  message: args.buildMessage(entryHandler),
@@ -28,6 +45,13 @@ function assertEntryHandlerHighRisk(args) {
28
45
  },
29
46
  });
30
47
  }
48
+ function undeclaredPipelineMessage(pipeline, operation) {
49
+ const cases = IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES.map((name) => `"${name}"`).join(" | ");
50
+ return (`${pipeline ? `"${pipeline}"` : "A request scope"} performs an irreversible ${operation} without ` +
51
+ "a directly dispatched entry handler and without a declared exception. A job or " +
52
+ `multi-stream projection that may do this declares irreversibleWithoutEntryHandler: ${cases}; ` +
53
+ 'anything else (route, afterCommit hook, agent tool call) dispatches a write handler with agent: { risk: "high" } instead.');
54
+ }
31
55
  // Stream handlers have no agent hint, so the "declare risk high" advice cannot apply to them.
32
56
  function highRiskRemedy(entryHandler) {
33
57
  return entryHandler.qn.includes(":stream:")
@@ -37,6 +61,7 @@ function highRiskRemedy(entryHandler) {
37
61
  export function assertIrreversibleOperationAllowed(operation) {
38
62
  assertEntryHandlerHighRisk({
39
63
  reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
64
+ operation,
40
65
  buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
41
66
  `"${entryHandler.risk}" — ${highRiskRemedy(entryHandler)}. The ` +
42
67
  "directly called handler must carry it; delegating via ctx.dispatch.write/writeAs does not.",
@@ -54,6 +79,7 @@ export function assertInstructionFieldWriteAllowed(entityName, verb, writtenFiel
54
79
  return;
55
80
  assertEntryHandlerHighRisk({
56
81
  reason: FrameworkReasons.instructionFieldWriteRequiresHighRisk,
82
+ operation: `${verb} of "${entityName}" field(s) ${fields.join(", ")} flagged readAsInstruction`,
57
83
  buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" ${verb}s "${entityName}" field(s) ${fields.join(", ")} ` +
58
84
  `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — ` +
59
85
  `${highRiskRemedy(entryHandler)}. The directly called handler must carry ` +
@@ -4,5 +4,7 @@ export type MeilisearchAdapterOptions = {
4
4
  apiKey: string;
5
5
  indexPrefix?: string;
6
6
  };
7
+ export declare const MEILI_INDEX_PREFIX_ENV = "KUMIKO_MEILI_INDEX_PREFIX";
8
+ export declare function resolveMeilisearchIndexPrefix(indexPrefix: string | undefined, env?: Readonly<Record<string, string | undefined>>): string;
7
9
  export declare function meilisearchTenantIndex(prefix: string, tenantId: TenantId): string;
8
10
  export declare function meilisearchDocId(entityType: string, entityId: EntityId): string;
@@ -1,3 +1,8 @@
1
+ export const MEILI_INDEX_PREFIX_ENV = "KUMIKO_MEILI_INDEX_PREFIX";
2
+ // The env beats the option so an e2e run isolates its server without the app passing anything.
3
+ export function resolveMeilisearchIndexPrefix(indexPrefix, env = process.env) {
4
+ return env[MEILI_INDEX_PREFIX_ENV] || (indexPrefix ?? "kumiko_");
5
+ }
1
6
  // Exported for unit tests (index-name / primary-key shape) without a live Meili.
2
7
  export function meilisearchTenantIndex(prefix, tenantId) {
3
8
  return `${prefix}t${tenantId}`;
@@ -1,5 +1,6 @@
1
1
  import { type MeilisearchAdapterOptions } from "./meilisearch-adapter-internals.ts";
2
2
  import type { SearchAdapter } from "./types.ts";
3
+ export { MEILI_INDEX_PREFIX_ENV } from "./meilisearch-adapter-internals.ts";
3
4
  /** A drop that finds its index already deleted by a concurrent drop (index_not_found, or the
4
5
  * vanished index files) has reached its end state. Reads a task error or an API error's cause. */
5
6
  export declare function isGoneIndexError(error: unknown): boolean;
@@ -1,8 +1,9 @@
1
1
  import { errorCodeOf, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
2
2
  import { importOptionalPeer } from "../utils/import-optional-peer.js";
3
- import { meilisearchTenantIndex, } from "./meilisearch-adapter-internals.js";
3
+ import { meilisearchTenantIndex, resolveMeilisearchIndexPrefix, } from "./meilisearch-adapter-internals.js";
4
4
  import { buildPieceDocuments, entityPiecesFilter, filterTypeClause, stalePiecesFilter, } from "./meilisearch-chunking.js";
5
5
  import { MEILISEARCH_PEER } from "./meilisearch-peer.js";
6
+ export { MEILI_INDEX_PREFIX_ENV } from "./meilisearch-adapter-internals.js";
6
7
  // meilisearch is an optional peer; a static import would fail with the runtime's bare
7
8
  // "Cannot find package" error instead of naming the peer and how to install it.
8
9
  const { ErrorStatusCode, Meilisearch } = await importOptionalPeer(MEILISEARCH_PEER, () => import("meilisearch"));
@@ -125,7 +126,7 @@ async function dropIndexesIfPresent(client, uids) {
125
126
  // legal. Replace anything else just in case callers pass unexpected shapes.
126
127
  export function createMeilisearchAdapter(options) {
127
128
  const client = new Meilisearch({ host: options.url, apiKey: options.apiKey });
128
- const prefix = options.indexPrefix ?? "kumiko_";
129
+ const prefix = resolveMeilisearchIndexPrefix(options.indexPrefix);
129
130
  // Set via setDefaultConfig once the registry is known (server.ts boot).
130
131
  // undefined until then — tenants stay unconfigured, matching prior behavior.
131
132
  let defaultConfig;
@@ -5,6 +5,7 @@ export type CardRoleColumn = {
5
5
  readonly type?: string;
6
6
  readonly renderer?: unknown;
7
7
  readonly hideOnNarrow?: boolean;
8
+ readonly narrowInline?: boolean;
8
9
  readonly fileDisplay?: {
9
10
  readonly kind: string;
10
11
  };
@@ -21,3 +22,4 @@ export type CardColumnRoles<C extends CardRoleColumn> = {
21
22
  };
22
23
  export declare function cardFileDisplayKind(type: string | undefined, renderer: unknown): "image" | "file" | undefined;
23
24
  export declare function cardColumnRoles<C extends CardRoleColumn>(columns: readonly C[]): CardColumnRoles<C>;
25
+ export declare function cardMetaLines<C extends CardRoleColumn>(meta: readonly C[]): readonly (readonly C[])[];
@@ -30,3 +30,18 @@ export function cardColumnRoles(columns) {
30
30
  const meta = textColumns.filter((col) => col !== title && col !== status && col !== lead && col.hideOnNarrow !== true);
31
31
  return { image, lead, title, status, meta };
32
32
  }
33
+ // A run of consecutive `narrowInline` columns shares one line; every other column has its own.
34
+ export function cardMetaLines(meta) {
35
+ const lines = [];
36
+ let previousWasInline = false;
37
+ for (const col of meta) {
38
+ const inline = col.narrowInline === true;
39
+ const last = lines[lines.length - 1];
40
+ if (inline && previousWasInline && last !== undefined)
41
+ last.push(col);
42
+ else
43
+ lines.push([col]);
44
+ previousWasInline = inline;
45
+ }
46
+ return lines;
47
+ }
@@ -11,14 +11,14 @@ export type { EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, Options
11
11
  export type { AccessRule } from "../engine/types/handlers.ts";
12
12
  export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
13
13
  export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
14
- export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessItems, ActionFormSuccessLink, ConfigEditAction, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListFooterLink, DashboardListNarrow, DashboardListPanel, DashboardListRowToneMarker, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelNarrow, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupLayout, DashboardStatGroupLink, DashboardStatGroupNarrow, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBulkAction, ListColumnHint, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListRowDecoration, ListSortOption, ListSortSpec, ListTableOptions, ListTableSummaryRow, MetricNavigate, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordBannerSpec, RecordBreadcrumbItem, RecordBreadcrumbSpec, RecordHeaderSubtitlePart, RecordNotice, RecordProgress, RecordProgressSpec, RecordProgressStep, RecordStep, RecordStepsSpec, RecordSummarySpec, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, ToolbarAction, } from "../engine/types/screen.ts";
14
+ export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessItems, ActionFormSuccessLink, ConfigEditAction, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListFooterLink, DashboardListNarrow, DashboardListPanel, DashboardListRowToneMarker, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelNarrow, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupLayout, DashboardStatGroupLink, DashboardStatGroupNarrow, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBulkAction, ListColumnHint, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListRowDecoration, ListSortOption, ListSortSpec, ListTableOptions, ListTableSummaryRow, ListToolbarActionsPlacement, MetricNavigate, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordBannerSpec, RecordBreadcrumbItem, RecordBreadcrumbSpec, RecordHeaderSubtitlePart, RecordNotice, RecordProgress, RecordProgressSpec, RecordProgressStep, RecordStep, RecordStepsSpec, RecordSummarySpec, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, ToolbarAction, } from "../engine/types/screen.ts";
15
15
  export { MAX_BULK_SELECTION } from "../engine/types/screen.ts";
16
16
  export type { TargetRef } from "../engine/types/target-ref.ts";
17
17
  export type { TreeAction } from "../engine/types/tree-node.ts";
18
18
  export type { WorkspaceDefinition } from "../engine/types/workspace.ts";
19
19
  export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.ts";
20
20
  export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app-schema.ts";
21
- export { CARD_META_MAX, cardColumnRoles } from "./card-column-roles.ts";
21
+ export { CARD_META_MAX, cardColumnRoles, cardMetaLines } from "./card-column-roles.ts";
22
22
  export { type Formality, formalLocaleTag } from "./formality.ts";
23
23
  export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, UNRESOLVED_REFERENCE_LABEL_KEYS, } from "./list-row-meta.ts";
24
24
  export { resolveTranslationValue, type TranslationValue, translationValueOtherText, } from "./plural.ts";
@@ -28,7 +28,7 @@ export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition,
28
28
  export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
29
29
  export { MAX_BULK_SELECTION } from "../engine/types/screen.js";
30
30
  export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
31
- export { CARD_META_MAX, cardColumnRoles } from "./card-column-roles.js";
31
+ export { CARD_META_MAX, cardColumnRoles, cardMetaLines } from "./card-column-roles.js";
32
32
  export { formalLocaleTag } from "./formality.js";
33
33
  export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, UNRESOLVED_REFERENCE_LABEL_KEYS, } from "./list-row-meta.js";
34
34
  export { resolveTranslationValue, translationValueOtherText, } from "./plural.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.414.0",
3
+ "version": "0.415.0",
4
4
  "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -204,7 +204,7 @@
204
204
  "./package.json": "./package.json"
205
205
  },
206
206
  "dependencies": {
207
- "@cosmicdrift/kumiko-types": "0.414.0",
207
+ "@cosmicdrift/kumiko-types": "0.415.0",
208
208
  "bullmq": "^5.81.5",
209
209
  "hono": "^4.13.14",
210
210
  "i18next": "^26.5.12",
@@ -226,7 +226,7 @@
226
226
  }
227
227
  },
228
228
  "devDependencies": {
229
- "@cosmicdrift/kumiko-testing": "0.414.0",
229
+ "@cosmicdrift/kumiko-testing": "0.415.0",
230
230
  "bun-types": "^1.4.4",
231
231
  "fflate": "^0.8.3",
232
232
  "meilisearch": "^0.62.0",
@@ -3,7 +3,9 @@ language js
3
3
  or {
4
4
  `new Date($...)` as $hit,
5
5
  `$target.toISOString($...)` as $hit,
6
- `$target.getTime($...)` as $hit
6
+ `$target.getTime($...)` as $hit,
7
+ `$target?.toISOString($...)` as $hit,
8
+ `$target?.getTime($...)` as $hit
7
9
  } where {
8
10
  register_diagnostic(span=$hit, message="JS Date API in production code: use Temporal.Now.instant(), Temporal.Instant.from(...), .toString() or .epochMilliseconds (ctx.tz for wall-clock + IANA zone). Date.now() and Date.parse() stay allowed. See docs/plans/architecture/timezones.md.", severity="error")
9
11
  }
@@ -12,5 +12,5 @@ or {
12
12
  },
13
13
  $url <: r"(?s)^[\"'`]/[^/$\\].*"
14
14
  },
15
- register_diagnostic(span=$call, message="Raw fetch() skips the SSRF policy in server code: use egress(policy)(...) from @cosmicdrift/kumiko-framework/http. In web screens use useQuery/useMutation or an API client (*.ts). A same-origin path literal (\"/api/...\") is allowed; any other exception needs a biome-ignore with a specific reason.", severity="error")
15
+ register_diagnostic(span=$call, message="Raw fetch() skips the SSRF policy in server code: use egress(policy)(...) from @cosmicdrift/kumiko-framework/http. In web screens use useQuery/useMutation or an API client (*.ts). A same-origin path literal (\"/api/...\") is allowed; in web code any other exception needs a biome-ignore with a specific reason, in server code only an entry in the reviewed security-plugin-suppression baseline.", severity="error")
16
16
  }
@@ -1,6 +1,12 @@
1
1
  language js
2
2
 
3
3
  `JSON.parse($input, $...)` as $call where {
4
- not { $call <: within JsTryStatement(body=$tryBlock), $call <: within $tryBlock },
4
+ not {
5
+ or {
6
+ $call <: within JsTryStatement(body=$tryBlock),
7
+ $call <: within JsTryFinallyStatement(body=$tryBlock, catch_clause=JsCatchClause())
8
+ },
9
+ $call <: within $tryBlock
10
+ },
5
11
  register_diagnostic(span=$call, message="Unguarded JSON.parse throws a SyntaxError on corrupt external input. Use parseJsonSafe (cache semantics) or parseJsonOrThrow (boundary semantics) from utils/safe-json, or wrap the call in try/catch.", severity="error")
6
12
  }
@@ -25,13 +25,15 @@
25
25
  "options": {
26
26
  "paths": {
27
27
  "temporal-polyfill": {
28
- "importNames": ["Temporal"],
29
28
  "message": "import { Temporal } from \"@cosmicdrift/kumiko-types/temporal\" instead — it prefers the native global, so framework and consumer share one set of Temporal classes."
30
- },
31
- "temporal-polyfill/global": {
29
+ }
30
+ },
31
+ "patterns": [
32
+ {
33
+ "group": ["temporal-polyfill/*"],
32
34
  "message": "import { Temporal } from \"@cosmicdrift/kumiko-types/temporal\" instead — it prefers the native global, so framework and consumer share one set of Temporal classes."
33
35
  }
34
- }
36
+ ]
35
37
  }
36
38
  }
37
39
  },
@@ -93,7 +95,7 @@
93
95
  "!**/*.integration.tsx",
94
96
  "!**/*.spec.ts",
95
97
  "!**/*.d.ts",
96
- "!**/safe-json.ts",
98
+ "!**/packages/framework/src/utils/safe-json.ts",
97
99
  "!**/packages/*/scripts/**",
98
100
  "!**/samples/**/scripts/**"
99
101
  ]
@@ -112,8 +114,8 @@
112
114
  "!**/*.integration.tsx",
113
115
  "!**/*.spec.ts",
114
116
  "!**/*.d.ts",
115
- "!**/errors/classes.ts",
116
- "!**/errors/reasons.ts",
117
+ "!**/packages/framework/src/errors/classes.ts",
118
+ "!**/packages/framework/src/errors/reasons.ts",
117
119
  "!**/packages/*/scripts/**",
118
120
  "!**/samples/**/scripts/**"
119
121
  ]
@@ -144,9 +146,9 @@
144
146
  "!**/*.integration.tsx",
145
147
  "!**/*.spec.ts",
146
148
  "!**/*.d.ts",
147
- "!**/scripts/migrations/**",
148
- "!**/samples/*/src/migration/**",
149
- "!**/event-store/admin-api.ts"
149
+ "!scripts/migrations/**",
150
+ "!samples/*/src/migration/**",
151
+ "!**/packages/framework/src/event-store/admin-api.ts"
150
152
  ]
151
153
  },
152
154
  {
package/src/changes.json CHANGED
@@ -1,4 +1,61 @@
1
1
  [
2
+ {
3
+ "version": "0.415.0",
4
+ "type": "fix",
5
+ "title": "CRUD schemas carry the reference target of their fields",
6
+ "detail": "`createReferenceField` built a bare `z.uuid()`, so `handlerFieldReference` found nothing on `r.crud` write handlers. Insert and update schemas now set the same `references` meta a hand-written handler schema uses, which lets an agent proposal name the referenced record instead of showing its id."
7
+ },
8
+ {
9
+ "version": "0.415.0",
10
+ "type": "breaking",
11
+ "title": "Whitespace-only translations and blank plural forms fail the boot check",
12
+ "detail": "The locale completeness check at boot treated a value of one space as present, so a button with that label rendered blank, and it treated every plural object as present. Whitespace-only strings and plurals with an empty or whitespace-only form now count as missing, and the i18n parity test applies the same rule to locale bundles.",
13
+ "migration": "Fill in each key the boot error lists. For a plural, fill in the blank form or remove it so the lookup falls back to `other`."
14
+ },
15
+ {
16
+ "version": "0.415.0",
17
+ "type": "breaking",
18
+ "title": "Irreversible operations without a write-handler entry need a declared exception",
19
+ "detail": "A job (`r.job`) or multi-stream projection that runs an irreversible operation without a write-handler entry now throws AccessDeniedError (`irreversible_operation_without_entry_handler`) instead of passing silently. Declare `irreversibleWithoutEntryHandler` with one of `rebuildable-derived-data`, `high-risk-or-cron-pipeline` or `per-dispatch-record-key`. The declaration covers only the job's or consumer's own code; afterCommit hooks, nested dispatches and agent tool calls inside it are still gated. Any other request scope without a write-handler entry is refused too: an afterCommit or afterRollback hook of an HTTP write, an HTTP route, a WebSocket handler. A refused job goes red and a refused consumer goes to the dead letter, while a refused hook is only logged, so its delete does not happen and only the log shows it.",
20
+ "migration": "Add `irreversibleWithoutEntryHandler: \"<case>\"` to each job or multi-stream projection that calls executor.forget, a hard delete, kms.eraseKey or writes a readAsInstruction field. Pick the case that names why no entry handler exists; if none fits, route the operation through a write handler with `agent: { risk: \"high\" }`. Hooks and routes that call one of these primitives directly must dispatch such a handler or a job instead."
21
+ },
22
+ {
23
+ "version": "0.415.0",
24
+ "type": "fix",
25
+ "title": "Global host gate skips readable hosts and where-rules and caps unpinned lists",
26
+ "detail": "Hosts classified `systemRowsReadable` (including reference data) keep their tenant-scope `EXISTS` instead of being resolved up front. A global host whose `access.read` is a `where` rule opens no arm in the system-scope host check, because no row level security acts there. An unpinned list skips soft-deleted join rows and resolves at most 5000 host ids; beyond that the global host arm is left out and a warning is logged."
27
+ },
28
+ {
29
+ "version": "0.415.0",
30
+ "type": "breaking",
31
+ "title": "Named filter refs carry `access` instead of `roles`",
32
+ "detail": "`NamedListFilterRef.roles` is replaced by `access` (an `AccessRule`), set by the framework from the entity filter's rule; an authored `access` is dropped like `roles` was. The client offers a chip with `isUiAccessGranted(ref.access, userRoles)`, so `anySignedIn` and `openToAll` follow the same rules as role-gated screens: `anySignedIn` opens a rule only next to the `anonymous` role, and `openToAll` needs a non-empty reason. Before, every rule form other than a plain role list was offered to everyone. `isNamedFilterOffered` is removed from the renderer.",
33
+ "migration": "Remove `roles` from `NamedListFilterRef` literals in screens (it was framework-owned and dropped anyway); the restriction is declared once as `access` on the entity's `namedFilters` entry. Code reading `ref.roles` from a built app schema reads `ref.access` instead."
34
+ },
35
+ {
36
+ "version": "0.415.0",
37
+ "type": "fix",
38
+ "title": "Handlers can no longer call the unbound delivery attempt log factory",
39
+ "detail": "`_deliveryAttemptLogFactory` was copied into `ctx.services`, so a handler could log delivery attempts for any tenant and recipient. It is now wiring; handlers keep the bound `_logOwnDeliveryAttempt`."
40
+ },
41
+ {
42
+ "version": "0.415.0",
43
+ "type": "fix",
44
+ "title": "One shared derivation of the list query keys the summary-row check expects",
45
+ "detail": "`listPayloadKeysSent` in `@cosmicdrift/kumiko-types/screen` turns a list screen's capabilities (searchable, filters, named filters, screen filter) into the optional query keys it sends. The boot validator's summary-row schema check uses it instead of a hand-written copy, and renderer tests run the real entityList and projectionList payload builders and compare their keys with it."
46
+ },
47
+ {
48
+ "version": "0.415.0",
49
+ "type": "fix",
50
+ "title": "Biome preset closes temporal-polyfill completely and tightens plugin gaps",
51
+ "detail": "noRestrictedImports now blocks every import from temporal-polyfill and temporal-polyfill/*, not only the Temporal name. no-date-api also flags optional calls (x?.toISOString(), x?.getTime()). unsafe-json-parse accepts JSON.parse in the try block of try/catch/finally. The allowlists of unsafe-json-parse, error-reasons and admin-api name the framework files by full path, so an app file with the same name no longer inherits the exception. lint-ignore-to-biome matches no-raw-hooks scope against the project-relative path from the plugin's own includes, lists trailing markers instead of converting them, and covers the remaining deleted guard slugs. The e2e Meilisearch teardown resolves MEILI_URL and MEILI_MASTER_KEY from webServer.env, then the app's .env files, then the default."
52
+ },
53
+ {
54
+ "version": "0.415.0",
55
+ "type": "fix",
56
+ "title": "x-kumiko-now is stamped after the handler ran",
57
+ "detail": "The header was set before the handler, so freshly written timestamps looked up to the handler runtime in the future to the client. It is now read after next(). The RLS boot catalog reads all policy shapes in one query instead of one per table. Boot rules now reject sortOptions dirs the projection query's sortDirection enum lacks, summaryRow.params keys the summary query does not know, and badgeDot on a hint column. LIST_TOOLBAR_ACTIONS_PLACEMENTS is the single source for toolbarActionsPlacement. billing-foundation process-event takes the subscription lock before reading the current subscription."
58
+ },
2
59
  {
3
60
  "version": "0.414.0",
4
61
  "type": "fix",