@dforge-core/metadata 0.0.19 → 0.0.20

package/dist/index.d.ts

@@ -1153,7 +1153,15 @@ interface MenuItemDef {
 interface MenuDef {
     label: string;
     description?: string;
-    /** Folder codes where this menu is available. */
+    /**
+     * Flat folder codes this menu is linked to — the module code for the root,
+     * module code + `_` + each nesting segment for children (`logistics_all_trips`).
+     * The full path, the module-relative path, and a folder's own key (while unique
+     * in the tree) resolve too. Omit to link the menu to every folder the module
+     * declares. Scopes the folder→menu link only: every folder in ui/folders.json is
+     * created either way. A code matching no folder — or a key two branches share —
+     * fails the install.
+     */
     folders?: string[];
     /** Menu items keyed by item code. */
     items: Record<string, MenuItemDef>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/metadata",
-	"version": "0.0.19",
+	"version": "0.0.20",
 	"description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
 	"license": "MIT",
 	"author": "dForge",

package/schemas/menus.schema.json

@@ -23,7 +23,7 @@
 				"folders": {
 					"type": "array",
 					"items": { "type": "string" },
-					"description": "Folder codes where this menu is available"
+					"description": "Flat folder codes this menu is linked to (module code for the root, module code + '_' + each nesting segment for children, e.g. 'logistics_all_trips'; the full path, the module-relative path, and a folder's own key when unique in the tree also resolve). Omit to link the menu to every folder the module declares. Scopes the folder-to-menu link only — every folder in ui/folders.json is created either way. A code matching no folder, or a key two branches share, fails the install."
 				},
 				"items": {
 					"type": "object",

package/schemas/triggers.schema.json

@@ -50,7 +50,7 @@
 				"async": {
 					"type": "boolean",
 					"default": true,
-					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. Keep async:false actions fast; they run on the request's transaction."
+					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. That holds for a trigger on ANOTHER module's entity too (the bridge shape): a bridge can veto its host's write, the same way a mandatory extension column already refuses one. Use it to enforce an invariant, not merely to react — the error names the blocking module and trigger (code TRIGGER_ACTION_FAIL), and a bug in the action blocks the host's workflow just as effectively as a real violation. Keep async:false actions fast; they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

package/src/menus.ts

@@ -26,7 +26,15 @@ export interface MenuItemDef {
 export interface MenuDef {
 	label: string;
 	description?: string;
-	/** Folder codes where this menu is available. */
+	/**
+	 * Flat folder codes this menu is linked to — the module code for the root,
+	 * module code + `_` + each nesting segment for children (`logistics_all_trips`).
+	 * The full path, the module-relative path, and a folder's own key (while unique
+	 * in the tree) resolve too. Omit to link the menu to every folder the module
+	 * declares. Scopes the folder→menu link only: every folder in ui/folders.json is
+	 * created either way. A code matching no folder — or a key two branches share —
+	 * fails the install.
+	 */
 	folders?: string[];
 	/** Menu items keyed by item code. */
 	items: Record<string, MenuItemDef>;