@cosmicdrift/kumiko-framework 0.415.0 → 0.417.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 (90) hide show
  1. package/agents/api/framework-engine.md +67 -13
  2. package/agents/api/framework-ui-types.md +81 -7
  3. package/agents/api/renderer-web.md +31 -3
  4. package/agents/api/types.md +114 -61
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +36 -4
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/embedded.md +24 -1
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/list-table-options.md +71 -5
  12. package/agents/examples/managed-config.md +9 -1
  13. package/agents/examples/record-detail-layout.md +71 -6
  14. package/agents/examples/secrets-demo.md +3 -1
  15. package/agents/examples/signature.md +187 -0
  16. package/agents/examples/writeform-section.md +330 -0
  17. package/agents/examples.md +2 -0
  18. package/agents/features-index.md +4 -0
  19. package/agents/features.md +14 -0
  20. package/dist/api/server-routes.js +2 -0
  21. package/dist/db/queries/event-store.d.ts +3 -0
  22. package/dist/db/queries/event-store.js +12 -0
  23. package/dist/db/table-builder.js +3 -1
  24. package/dist/engine/boot-validator/boot-phases.js +5 -0
  25. package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
  26. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  27. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  28. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  29. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  30. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  31. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  33. package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
  34. package/dist/engine/boot-validator/list-row-guidance.js +31 -0
  35. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  36. package/dist/engine/boot-validator/list-table-options.js +8 -6
  37. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  38. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  39. package/dist/engine/boot-validator/query-output-columns.js +22 -0
  40. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  41. package/dist/engine/boot-validator/query-refs.js +4 -1
  42. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  43. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  44. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  45. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  46. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  47. package/dist/engine/boot-validator/screens-actions.js +57 -15
  48. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  49. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  50. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  51. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  52. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  53. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  54. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  55. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  56. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  57. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  58. package/dist/engine/boot-validator/screens-forms.js +108 -2
  59. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  60. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  61. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
  62. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
  63. package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
  64. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  65. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-lists.js +4 -1
  68. package/dist/engine/boot-validator/screens.js +1 -2
  69. package/dist/engine/bridge-stub.js +1 -0
  70. package/dist/engine/build-config-feature-schema.js +29 -36
  71. package/dist/engine/config-access-rules.d.ts +3 -0
  72. package/dist/engine/config-access-rules.js +34 -0
  73. package/dist/engine/factories.d.ts +2 -0
  74. package/dist/engine/project-app-schema-for-roles.js +2 -0
  75. package/dist/engine/screen-helpers.js +7 -3
  76. package/dist/event-store/archive.d.ts +1 -0
  77. package/dist/event-store/archive.js +5 -1
  78. package/dist/event-store/event-store.d.ts +5 -0
  79. package/dist/event-store/event-store.js +23 -3
  80. package/dist/files/file-routes.d.ts +2 -0
  81. package/dist/files/file-routes.js +85 -22
  82. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  83. package/dist/files/foreign-tenant-file-read.js +64 -0
  84. package/dist/i18n/required-surface-keys.js +32 -6
  85. package/dist/pipeline/handler-context-events.js +15 -1
  86. package/dist/ui-types/card-column-roles.d.ts +3 -0
  87. package/dist/ui-types/card-column-roles.js +9 -5
  88. package/dist/ui-types/index.d.ts +1 -1
  89. package/package.json +3 -3
  90. package/src/changes.json +48 -0
@@ -20,6 +20,10 @@ shared chrome (footer, submit button) can be compared side by side.
20
20
  - `note-detail`, a `projectionDetail` screen whose only section is
21
21
  `kind: "writeForm"` with the identical field set, dispatching its own
22
22
  `note-desk:write:note:comment` handler on submit
23
+ - `note-triage`, an `actionForm`: `infoBand` draws the `assist` banner; the layout field
24
+ options `badge` (`{ label, tone }`) and `hintField` (a value field as muted hint) and a
25
+ `suffix` behind the number field. `FormProps.topBanner` is not shown: no screen
26
+ declaration reaches it
23
27
  - an e2e layout-parity spec (`e2e/writeform-parity.spec.ts`) proving both
24
28
  submit buttons render the same width, sit right-aligned in their form's
25
29
  footer, and never stretch full-width — the regression this recipe guards
@@ -606,6 +610,7 @@ import {
606
610
  sectionFieldSpecs,
607
611
  validateBoot as validateBootRaw,
608
612
  } from "@cosmicdrift/kumiko-framework/engine";
613
+ import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
609
614
  import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
610
615
  import { z } from "zod";
611
616
  import { noteDeskFeature } from "../feature";
@@ -651,6 +656,7 @@ describe("writeform-section sample — registration", () => {
651
656
  editSection === undefined ||
652
657
  editSection.kind === "extension" ||
653
658
  editSection.kind === "relatedList" ||
659
+ editSection.kind === "stepList" ||
654
660
  detailSection?.kind !== "writeForm"
655
661
  ) {
656
662
  throw new Error("expected an entityEdit fields section and a writeForm section");
@@ -711,6 +717,233 @@ describe("writeform-section sample — boot-validator catches author mistakes",
711
717
  );
712
718
  });
713
719
  });
720
+
721
+ describe("writeform-section sample — submitWith and narrow options", () => {
722
+ test("note-approval registers the form with submitWith and tab labels", () => {
723
+ expect(() => validateBoot([noteDeskFeature])).not.toThrow();
724
+ const screen = registry.getScreen("note-desk:screen:note-approval");
725
+ if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
726
+ const form = screen.layout.sections[0];
727
+ if (form?.kind !== "writeForm") throw new Error("expected writeForm section");
728
+ expect(form.submitWith).toBe("approve");
729
+ expect(screen.layout.sections.map((s) => s.tabLabel)).toEqual(["Review", "History"]);
730
+ expect(screen.layout.narrowTabs).toBe(false);
731
+ });
732
+
733
+ function approvalFeature(options: {
734
+ readonly submitWith: string;
735
+ readonly payload?: { readonly map: Record<string, string> };
736
+ readonly fields?: readonly string[];
737
+ }) {
738
+ return defineFeature("approval-desk", (r) => {
739
+ r.translations({
740
+ keys: {
741
+ "screen:x.title": { en: "X" },
742
+ "approval-desk:entity:__write-form-section__:field:name": { en: "Name" },
743
+ "approval-desk:entity:__write-form-section__:field:noteId": { en: "Note" },
744
+ },
745
+ });
746
+ const access = {
747
+ openToAll: { reason: "test handler callable by any signed-in test user" },
748
+ } as const;
749
+ r.queryHandler({
750
+ name: "foo:detail",
751
+ schema: z.object({ id: z.string() }),
752
+ handler: async () => ({}),
753
+ access,
754
+ });
755
+ r.writeHandler({
756
+ name: "approve",
757
+ schema: z.object({}).passthrough(),
758
+ handler: async () => ({ isSuccess: true as const, data: null }),
759
+ access,
760
+ });
761
+ const text = createTextField({ personal: false, reason: "is_business_data" });
762
+ r.screen({
763
+ id: "x",
764
+ type: "projectionDetail",
765
+ query: "approval-desk:query:foo:detail",
766
+ layout: {
767
+ sections: [
768
+ {
769
+ kind: "writeForm",
770
+ title: "s",
771
+ fieldDefs: { name: text, noteId: text },
772
+ fields: options.fields ?? ["name"],
773
+ handler: "approval-desk:write:approve",
774
+ submitWith: options.submitWith,
775
+ },
776
+ ],
777
+ },
778
+ actions: [
779
+ {
780
+ id: "approve",
781
+ label: "Approve",
782
+ handler: "approval-desk:write:approve",
783
+ ...(options.payload !== undefined && { payload: options.payload }),
784
+ },
785
+ ],
786
+ });
787
+ });
788
+ }
789
+
790
+ test("in a tabs layout the submitWith action must be limited to the form's tab", () => {
791
+ const tabsFeature = (showOnTabs: readonly string[] | undefined) =>
792
+ defineFeature("tabs-desk", (r) => {
793
+ r.translations({
794
+ keys: {
795
+ "screen:x.title": { en: "X" },
796
+ "tabs-desk:entity:__write-form-section__:field:name": { en: "Name" },
797
+ },
798
+ });
799
+ const access = {
800
+ openToAll: { reason: "test handler callable by any signed-in test user" },
801
+ } as const;
802
+ r.queryHandler({
803
+ name: "foo:detail",
804
+ schema: z.object({ id: z.string() }),
805
+ handler: async () => ({}),
806
+ access,
807
+ });
808
+ r.writeHandler({
809
+ name: "approve",
810
+ schema: z.object({}).passthrough(),
811
+ handler: async () => ({ isSuccess: true as const, data: null }),
812
+ access,
813
+ });
814
+ const text = createTextField({ personal: false, reason: "is_business_data" });
815
+ r.screen({
816
+ id: "x",
817
+ type: "projectionDetail",
818
+ query: "tabs-desk:query:foo:detail",
819
+ layout: {
820
+ mode: "tabs",
821
+ sections: [
822
+ {
823
+ id: "review",
824
+ kind: "writeForm",
825
+ title: "s",
826
+ fieldDefs: { name: text },
827
+ fields: ["name"],
828
+ handler: "tabs-desk:write:approve",
829
+ submitWith: "approve",
830
+ },
831
+ { id: "log", title: "Log", fields: ["name"] },
832
+ ],
833
+ },
834
+ actions: [
835
+ {
836
+ id: "approve",
837
+ label: "Approve",
838
+ handler: "tabs-desk:write:approve",
839
+ ...(showOnTabs !== undefined && { showOnTabs }),
840
+ },
841
+ ],
842
+ });
843
+ });
844
+ expect(() => validateBoot([tabsFeature(undefined)])).toThrow('showOnTabs: ["<that id>"]');
845
+ expect(() => validateBoot([tabsFeature(["review", "log"])])).toThrow("showOnTabs");
846
+ expect(() => validateBoot([tabsFeature(["review"])])).not.toThrow();
847
+ });
848
+
849
+ test("submitWith that names no action of the screen fails boot", () => {
850
+ expect(() => validateBoot([approvalFeature({ submitWith: "missing" })])).toThrow(
851
+ 'sets submitWith "missing"',
852
+ );
853
+ });
854
+
855
+ test("a form field that the action also sends in its payload fails boot", () => {
856
+ expect(() =>
857
+ validateBoot([
858
+ approvalFeature({
859
+ submitWith: "approve",
860
+ payload: { map: { noteId: "id" } },
861
+ fields: ["name", "noteId"],
862
+ }),
863
+ ]),
864
+ ).toThrow('has the field "noteId"');
865
+ });
866
+
867
+ test("a valid submitWith boots", () => {
868
+ expect(() =>
869
+ validateBoot([
870
+ approvalFeature({ submitWith: "approve", payload: { map: { noteId: "id" } } }),
871
+ ]),
872
+ ).not.toThrow();
873
+ });
874
+ });
875
+
876
+ describe("writeform-section sample — presentation options are checked at boot", () => {
877
+ function detailFeature(
878
+ layout: ProjectionDetailScreenDefinition["layout"],
879
+ actions?: ProjectionDetailScreenDefinition["actions"],
880
+ ) {
881
+ return defineFeature("layout-desk", (r) => {
882
+ r.translations({ keys: { "screen:x.title": { en: "X" } } });
883
+ r.queryHandler({
884
+ name: "foo:detail",
885
+ schema: z.object({ id: z.string() }),
886
+ handler: async () => ({}),
887
+ access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
888
+ });
889
+ r.screen({
890
+ id: "x",
891
+ type: "projectionDetail",
892
+ query: "layout-desk:query:foo:detail",
893
+ layout,
894
+ ...(actions !== undefined && { actions }),
895
+ });
896
+ });
897
+ }
898
+ const fields = ["name"];
899
+
900
+ test("hideOnNarrow together with showOnNarrowOnly fails", () => {
901
+ expect(() =>
902
+ validateBoot([
903
+ detailFeature({ sections: [{ fields, hideOnNarrow: true, showOnNarrowOnly: true }] }),
904
+ ]),
905
+ ).toThrow("hideOnNarrow and showOnNarrowOnly");
906
+ });
907
+
908
+ test("tabLabel and narrowTabs without tabs mode fail", () => {
909
+ expect(() =>
910
+ validateBoot([detailFeature({ sections: [{ fields, tabLabel: "Tab" }] })]),
911
+ ).toThrow("tabLabel without layout.mode");
912
+ expect(() =>
913
+ validateBoot([detailFeature({ narrowTabs: false, sections: [{ fields }] })]),
914
+ ).toThrow("narrowTabs without layout.mode");
915
+ });
916
+
917
+ test("photoGrid.badgeFirst without badgeField fails", () => {
918
+ expect(() =>
919
+ validateBoot([
920
+ detailFeature({
921
+ sections: [
922
+ {
923
+ kind: "relatedList",
924
+ title: "Photos",
925
+ query: "layout-desk:query:foo:detail",
926
+ parentParam: "id",
927
+ columns: [{ field: "name", label: "Name" }],
928
+ photoGrid: { imageField: "name", badgeFirst: true },
929
+ },
930
+ ],
931
+ }),
932
+ ]),
933
+ ).toThrow("badgeFirst without badgeField");
934
+ });
935
+
936
+ test("a navigate action with icon: false needs no icon", () => {
937
+ const action = {
938
+ kind: "navigate" as const,
939
+ id: "open-board",
940
+ label: "Board",
941
+ screen: "x",
942
+ icon: false as const,
943
+ };
944
+ expect(() => validateBoot([detailFeature({ sections: [{ fields }] }, [action])])).not.toThrow();
945
+ });
946
+ });
714
947
  ```
715
948
 
716
949
  ### src/feature.ts
@@ -770,11 +1003,21 @@ const commentPayloadSchema = z.object({
770
1003
  priority: z.number().optional(),
771
1004
  });
772
1005
 
1006
+ const approvePayloadSchema = z.object({
1007
+ noteId: z.string(),
1008
+ title: z.string().optional(),
1009
+ body: z.string().optional(),
1010
+ });
1011
+
773
1012
  export const noteDeskFeature = defineFeature("note-desk", (r) => {
774
1013
  r.translations({
775
1014
  keys: {
776
1015
  "screen:note-edit.title": { en: "Edit note" },
777
1016
  "screen:note-detail.title": { en: "Note" },
1017
+ "screen:note-triage.title": { en: "Triage note" },
1018
+ "note-desk:triage.info-band": { en: "Check the category, then send the note on." },
1019
+ "note-desk:triage.badge-review": { en: "Needs review" },
1020
+ "note-desk:triage.priority-suffix": { en: "pts" },
778
1021
  "note-desk:entity:note:field:title": { en: "Title" },
779
1022
  "note-desk:entity:note:field:body": { en: "Body" },
780
1023
  "note-desk:entity:note:field:category": { en: "Category" },
@@ -838,6 +1081,93 @@ export const noteDeskFeature = defineFeature("note-desk", (r) => {
838
1081
  },
839
1082
  access: open.access,
840
1083
  });
1084
+
1085
+ // An actionForm reaches the "assist" banner through `infoBand`; the layout field options
1086
+ // `badge`, `hintField` and `suffix` work on any form layout.
1087
+ r.screen({
1088
+ id: "note-triage",
1089
+ type: "actionForm",
1090
+ handler: "note-desk:write:note:comment",
1091
+ dormant: true,
1092
+ infoBand: "note-desk:triage.info-band",
1093
+ fields: {
1094
+ title: NOTE_FIELDS.title,
1095
+ body: NOTE_FIELDS.body,
1096
+ category: NOTE_FIELDS.category,
1097
+ priority: NOTE_FIELDS.priority,
1098
+ },
1099
+ layout: {
1100
+ sections: [
1101
+ {
1102
+ columns: 1,
1103
+ fields: [
1104
+ { field: "title", badge: { label: "note-desk:triage.badge-review", tone: "warn" } },
1105
+ { field: "category" },
1106
+ { field: "body", hintField: "category" },
1107
+ { field: "priority", suffix: "note-desk:triage.priority-suffix" },
1108
+ ],
1109
+ },
1110
+ ],
1111
+ },
1112
+ access: open.access,
1113
+ });
1114
+
1115
+ r.writeHandler({
1116
+ name: "note:approve",
1117
+ schema: approvePayloadSchema,
1118
+ handler: async () => ({ isSuccess: true as const, data: null }),
1119
+ ...open,
1120
+ });
1121
+
1122
+ // The footer action "approve" submits the form: one write with its own payload (noteId)
1123
+ // plus the form values, after form validation. The tab strip is phone-free; the "Review"
1124
+ // section stands above the "History" section there.
1125
+ r.screen({
1126
+ id: "note-approval",
1127
+ type: "projectionDetail",
1128
+ query: "note-desk:query:note:summary",
1129
+ layout: {
1130
+ mode: "tabs",
1131
+ narrowTabs: false,
1132
+ sections: [
1133
+ {
1134
+ id: "review",
1135
+ tabLabel: "Review",
1136
+ kind: "writeForm",
1137
+ title: "Decision",
1138
+ description: "Confirm the note and leave a reason.",
1139
+ descriptionNarrow: "Leave a reason.",
1140
+ columns: 1,
1141
+ fieldDefs: {
1142
+ title: NOTE_FIELDS.title,
1143
+ body: NOTE_FIELDS.body,
1144
+ },
1145
+ fields: ["title", { field: "body", hideOnNarrow: true }],
1146
+ handler: "note-desk:write:note:approve",
1147
+ submitWith: "approve",
1148
+ },
1149
+ {
1150
+ id: "history",
1151
+ tabLabel: "History",
1152
+ title: "History",
1153
+ titleOnNarrow: false,
1154
+ fields: ["category", "priority"],
1155
+ },
1156
+ ],
1157
+ },
1158
+ actions: [
1159
+ {
1160
+ id: "approve",
1161
+ label: "Approve",
1162
+ handler: "note-desk:write:note:approve",
1163
+ payload: { map: { noteId: "id" } },
1164
+ // Tabs layout: only the tab that mounts the form may show the action.
1165
+ showOnTabs: ["review"],
1166
+ },
1167
+ ],
1168
+ footerActions: ["approve"],
1169
+ access: open.access,
1170
+ });
841
1171
  });
842
1172
  ```
843
1173
 
@@ -42,6 +42,7 @@
42
42
  | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
43
43
  | `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.services.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
44
44
  | `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
45
+ | `handbook-knowledge` | The handbook-knowledge bundled feature: a fixed handbook JSON served to the AI assistant as list-pages and read-page query tools. | `examples/handbook-knowledge.md` |
45
46
  | `helpdesk` | Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client. | `examples/helpdesk.md` |
46
47
  | `host-routing` | createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server. | `examples/host-routing.md` |
47
48
  | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
@@ -74,6 +75,7 @@
74
75
  | `security-baseline` | composeSecurityStack(): sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing. | `examples/security-baseline.md` |
75
76
  | `seed-migration` | ES-Operations seed-migrations — file-based diff-and-apply für Aggregate-Updates die idempotent-Seeder nicht erfassen. | `examples/seed-migration.md` |
76
77
  | `session-revocation` | createSessionCallbacks + sessionChecker — server-side session revocation via JWT jti. | `examples/session-revocation.md` |
78
+ | `signature` | The signature bundled feature: a request for several signers, a signing link that is delivered by the app, and a completed PDF with a signature page. | `examples/signature.md` |
77
79
  | `state-machine` | Enforced entity state transitions. No more illegal state changes. | `examples/state-machine.md` |
78
80
  | `tags-basic` | Tag and group any entity without changing it — host-agnostic, event-sourced. | `examples/tags-basic.md` |
79
81
  | `tenant-inactivity` | tenant-inactivity: warn abandoned free accounts, then file the regular tenant-lifecycle deletion request; tier-based exemption and a keep-account link. | `examples/tenant-inactivity.md` |
@@ -90,6 +90,8 @@ One entry per feature a package ships: purpose, import of its factory, required
90
90
  `import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft"`
91
91
  - `form-draft-user-data`: GDPR (Art.
92
92
  `import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data"`; requires `user-data-rights`
93
+ - `handbook-knowledge`: Gives the AI agent the app's handbook as two read-only query tools: `list-pages` returns the catalog of task and screen pages with the questions each answers, `read-page` returns one page in the caller's language with a fallback to the default language and a fixed length cap.
94
+ `import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge"`
93
95
  - `helpdesk`: Helpdesk inbox: an anonymous browser client (GET /helpdesk/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin.
94
96
  `import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
95
97
  - `host-routing`: Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp's hostDispatch.
@@ -144,6 +146,8 @@ One entry per feature a package ships: purpose, import of its factory, required
144
146
  `import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo"`; requires `config`
145
147
  - `sessions`: Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`.
146
148
  `import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions"`; requires `user`, `auth-foundation`
149
+ - `signature`: Signature requests: a signed-in user asks several people to sign one PDF of the tenant.
150
+ `import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature"`; requires `files`, `user-data-rights`
147
151
  - `step-dispatcher`: Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits.
148
152
  `import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher"`; requires `secrets`
149
153
  - `subscription-mollie`: Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case.
@@ -397,6 +397,12 @@ Requires: `user-data-rights`
397
397
 
398
398
  Optional requires: `form-draft`
399
399
 
400
+ ## handbook-knowledge
401
+
402
+ Gives the AI agent the app's handbook as two read-only query tools: `list-pages` returns the catalog of task and screen pages with the questions each answers, `read-page` returns one page in the caller's language with a fallback to the default language and a fixed length cap. The pages come from a build-time JSON (`kumiko handbuch knowledge`), so no table, projection or search index is involved and the handbook text stays public content.
403
+
404
+ Category: ai
405
+
400
406
  ## helpdesk
401
407
 
402
408
  Helpdesk inbox: an anonymous browser client (GET /helpdesk/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin. Every request is stored platform-wide and every SystemAdmin is notified by mail, optionally also in a Telegram chat (option `telegram`, off by default); the notification names only the kind, the app and a link, never name, address, phone, subject or message, because mail and Telegram cannot be shredded. SystemAdmins reply by mail (Reply-To set, attachments, quoting the original) and mark requests done; a website sender gets a fixed acknowledgement, a signed-in reporter a copy and an in-app note. Personal data is crypto-shredding-ready and the EXT_USER_DATA hooks export and erase a user's requests.
@@ -660,6 +666,14 @@ Requires: `user`, `auth-foundation`
660
666
 
661
667
  Exposes APIs: `sessions.revokeAllForUser`
662
668
 
669
+ ## signature
670
+
671
+ Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined and expired report the outcome; signer name, email, image, IP and user agent are personal data.
672
+
673
+ Category: data
674
+
675
+ Requires: `files`, `user-data-rights`
676
+
663
677
  ## step-dispatcher
664
678
 
665
679
  Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. An `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event enqueues one `step-dispatcher:job:deliver` BullMQ job per dispatch (Redis carries only the stream id and tenant, never the request payload). The job performs the actual HTTP or mail delivery and appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream, so the outcome is recorded in the event log without a separate status table. Transient failures (network error, timeout, 5xx, 408, 429, any mail adapter failure) are retried 3 times with exponential backoff; the outcome is recorded after the final attempt and the payload key is erased only then. A request that still has no outcome after 24 hours (job stalled or lost, or its final attempt could not record one) is closed by the daily `step-dispatcher:job:sweep-abandoned` cron (it pages through all such requests; requests that already have an outcome are not swept) with a generic `dispatch-failed` event and its payload key is erased. Permanent failures (invalid url, blocked host, other 4xx, unavailable auth secret) are recorded immediately. At most 2 deliveries per tenant run at once (`maxPerTenant` with `onLimit: "defer"`), so a slow receiver of one tenant does not delay other tenants. Requires a job runner (Redis) and a worker consuming the job's default `worker` lane; without a job runner the projection fails loudly. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across retries and redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.
@@ -1,6 +1,7 @@
1
1
  import { createProjectingTenantDb } from "../db/tenant-db.js";
2
2
  import { isAnonymousSessionUser } from "../engine/system-user.js";
3
3
  import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
4
+ import { createForeignTenantFileReadCheck } from "../files/foreign-tenant-file-read.js";
4
5
  import { createRecordReadCheck } from "../files/record-read-check.js";
5
6
  import { createRecordWriteCheck } from "../files/record-write-check.js";
6
7
  import { createRateLimitResolver } from "../rate-limit/index.js";
@@ -93,6 +94,7 @@ export function mountFileRoutes(app, wiring) {
93
94
  ...(fileRateLimitResolver ? { rateLimitResolver: fileRateLimitResolver } : {}),
94
95
  clientIpResolver: wiring.clientIpResolver,
95
96
  canReadRecord,
97
+ canReadForeignTenantFile: createForeignTenantFileReadCheck(options.registry, dispatcher.query),
96
98
  canWriteRecord: createRecordWriteCheck({
97
99
  registry: options.registry,
98
100
  canReadRecord,
@@ -30,6 +30,9 @@ export declare function insertFirstEventRow(db: AnyDb, params: FirstEventInsertP
30
30
  export declare function insertSubsequentEventRow(db: AnyDb, params: SubsequentEventInsertParams): Promise<SubsequentEventInsertRow | undefined>;
31
31
  export declare function selectStreamMaxVersion(db: AnyDb, aggregateId: string, tenantId: string): Promise<number>;
32
32
  export declare function selectStreamMaxVersions(db: AnyDb, aggregateIds: readonly string[], tenantId: string): Promise<Map<string, number>>;
33
+ /** Raw driver rows of the matching events (columns as in kumiko_events), ordered by the global id. */
34
+ export declare function selectEventRowsOfAggregatesByType(db: AnyDb, tenantId: string, aggregateIds: readonly string[], eventTypes: readonly string[]): Promise<readonly Record<string, unknown>[]>;
35
+ export declare function selectArchivedAggregateIdsOf(db: AnyDb, tenantId: string, aggregateIds: readonly string[]): Promise<readonly string[]>;
33
36
  /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
34
37
  export declare function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number>;
35
38
  export declare function selectEventsHighWaterMark(db: AnyDb): Promise<bigint>;
@@ -217,6 +217,18 @@ export async function selectStreamMaxVersions(db, aggregateIds, tenantId) {
217
217
  }
218
218
  return versions;
219
219
  }
220
+ /** Raw driver rows of the matching events (columns as in kumiko_events), ordered by the global id. */
221
+ export async function selectEventRowsOfAggregatesByType(db, tenantId, aggregateIds, eventTypes) {
222
+ if (aggregateIds.length === 0 || eventTypes.length === 0)
223
+ return [];
224
+ return unsafeReadRetrying(db, `SELECT * FROM "kumiko_events" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[]) AND "type" = ANY($3::text[]) ORDER BY "id" ASC`, [tenantId, toPostgresArrayLiteral(aggregateIds), toPostgresArrayLiteral(eventTypes)]);
225
+ }
226
+ export async function selectArchivedAggregateIdsOf(db, tenantId, aggregateIds) {
227
+ if (aggregateIds.length === 0)
228
+ return [];
229
+ const rows = await unsafeReadRetrying(db, `SELECT "aggregate_id" FROM "kumiko_archived_streams" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[])`, [tenantId, toPostgresArrayLiteral(aggregateIds)]);
230
+ return rows.map((row) => row.aggregate_id);
231
+ }
220
232
  /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
221
233
  export async function selectAggregateMaxVersion(db, aggregateId) {
222
234
  const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`, [aggregateId]);
@@ -103,7 +103,9 @@ const COLUMN_EMITTERS = {
103
103
  embedded: (name, snakeName, field) => ({
104
104
  [name]: field.multiple === true ? emptyJsonbArray(snakeName) : emptyJsonbObject(snakeName),
105
105
  }),
106
- jsonb: (name, snakeName) => ({ [name]: emptyJsonbObject(snakeName) }),
106
+ jsonb: (name, snakeName, field) => ({
107
+ [name]: field.emptyValue === "array" ? emptyJsonbArray(snakeName) : emptyJsonbObject(snakeName),
108
+ }),
107
109
  date: singleColumnNotNullWhenRequired(plainDate),
108
110
  timestamp: singleColumnNotNullWhenRequired(instant),
109
111
  tz: singleColumnNotNullWhenRequired(text),
@@ -3,6 +3,7 @@ import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
3
3
  import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.js";
4
4
  import { collectExposedApis } from "./boot-context.js";
5
5
  import { validateCircularDeps, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, } from "./config-deps.js";
6
+ import { validateCrossTenantFileRead } from "./cross-tenant-file-read.js";
6
7
  import { validateSqlDerivedFields } from "./derived-sql-fields.js";
7
8
  import { collectDetailForScreens } from "./detail-screens.js";
8
9
  import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateExtendSchemaCollisions, validateFileFields, validateHandlerAccess, validateLocatedTimestamps, validateLockedWhen, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
@@ -107,6 +108,10 @@ const FEATURE_CHECKS = [
107
108
  run: (f, c) => validateOwnershipRules(f, c.allClaimKeys, c.knownRoles),
108
109
  },
109
110
  { check: "validateReadGates", run: (f, c) => validateReadGates(f, c.featureMap) },
111
+ {
112
+ check: "validateCrossTenantFileRead",
113
+ run: (f, c) => validateCrossTenantFileRead(f, c.queryHandlerQns),
114
+ },
110
115
  { check: "validateTransferGraph", run: (f, c) => validateTransferGraph(f, c.featureMap) },
111
116
  { check: "validateMultiStreamProjections", run: (f) => validateMultiStreamProjections(f) },
112
117
  ];