@dforge-core/metadata 0.0.1

package/src/filter.ts

@@ -0,0 +1,34 @@
+// Canonical dForge filter expression.
+//
+// One shape shared by data views, reports, folders (row-level security) and the
+// API: either a single condition `{c, o, v}` or a group `{g, i: [...]}`. Mirror
+// of the `filter` $def repeated across data_views / reports / folders schemas.
+
+/** A single filter condition. */
+export interface FilterCondition {
+	/** Column code (supports dot navigation: 'customer.name'). */
+	c: string;
+	/** Operator: eq, neq, =, !=, gt, gtEq, lt, ltEq, in, nIn, like, isNull, … */
+	o: string;
+	/** Comparison value: scalar, array (in/nIn) or a `@param_code` reference. */
+	v?: unknown;
+}
+
+/** A boolean group of nested conditions/sub-groups. */
+export interface FilterGroup {
+	/** Group combinator. */
+	g: "and" | "or";
+	/** Group items: nested conditions or sub-groups. */
+	i: Filter[];
+}
+
+/** A filter is either a single condition or a group. */
+export type Filter = FilterCondition | FilterGroup;
+
+/** A sort clause `{ c, d }` as used by reports / per-source order. */
+export interface SortClause {
+	/** Column code. */
+	c: string;
+	/** Sort direction (default: asc). */
+	d?: "asc" | "desc";
+}

package/src/folders.ts

@@ -0,0 +1,39 @@
+// Folders — authoring shape of `folders.json`. Mirror of folders.schema.json.
+//
+// The file IS the root folder (not a map keyed by code); sub-folders live under
+// `children`, keyed by folder code.
+
+import type { Filter } from "./filter";
+
+/** Per-entity binding within a folder. */
+export interface FolderEntityBinding {
+	/** Data view code to use in this folder (commonly 'default'). */
+	viewName?: string;
+	/** Enable the quick-add (+) button for this entity here. */
+	quickAdd?: boolean;
+	/** Row-level filter: a SQL expression string or a canonical filter object. */
+	rowFilter?: string | Filter;
+}
+
+/** A folder node (the folders.json root, and each entry under `children`). */
+export interface FolderDef {
+	label?: string;
+	description?: string;
+	/** Parent folder code (only used by sparse-tree imports; usually omitted). */
+	parentCode?: string | null;
+	/** URL-friendly folder path override. */
+	folderPath?: string;
+	/** Accent color (hex, e.g. '#2196F3'). */
+	color?: string;
+	/** Bootstrap icon class (e.g. 'bi-folder'). */
+	icon?: string;
+	/** Inherit security rights from the parent folder (default true). */
+	inheritSecurity?: boolean;
+	/** Entity code → folder-entity binding. */
+	entities?: Record<string, FolderEntityBinding>;
+	/** Nested folders keyed by sub-folder code (recursive). */
+	children?: Record<string, FolderDef>;
+}
+
+/** A `folders.json` file: the root folder itself. */
+export type FoldersFile = FolderDef;

package/src/index.ts

@@ -0,0 +1,109 @@
+// @dforge-core/metadata — canonical dForge authoring registries + module-file types.
+//
+// Single source of truth for:
+//   • registries — field types, base datatypes, column types, traits, data-view
+//     kinds, report viz/chart types, plus helpers that derive physical metadata
+//     from a friendly field-type choice;
+//   • structural types — the authoring shape of every module-package file
+//     (manifest, entities, data views, reports, menus, folders, roles, settings,
+//     jobs, triggers, webhooks, print templates, seed data, actions), mirrored
+//     from the JSON schemas under docs/schemas/.
+//
+// No runtime dependencies; safe to import from editors, the web app, the CLI,
+// the MCP server and the VS Code extension.
+
+// ── Shared core types & registries ──────────────────────────────────────────
+export type {
+	AlignType,
+	BaseDatatypeCd,
+	ColumnTypeCd,
+	ColumnTypeDef,
+	FieldDef,
+	FieldLink,
+	FieldOption,
+	FieldTypeCd,
+	FieldTypeDef,
+	FlagCd,
+	NamedKind,
+	TraitDef,
+} from "./types";
+
+export { AggType, AGG_TYPE_LIST } from "./aggregation";
+
+export { fieldTypes, fieldTypeCds, isFieldTypeCd, getFieldType, fieldTypesByColumnType } from "./field-types";
+export { baseDatatypes, baseToDbDatatype } from "./base-datatypes";
+export { columnTypes, getColumnType } from "./column-types";
+export { traits, getTrait, expandTrait, expandTraits } from "./traits";
+export {
+	deriveDbDatatype,
+	deriveBaseDatatype,
+	defaultParams,
+	NUMERIC_TOTAL,
+	type DeriveOptions,
+} from "./derive";
+
+// ── Shared filter expression (data views / reports / folders / API) ──────────
+export type { Filter, FilterCondition, FilterGroup, SortClause } from "./filter";
+
+// ── Module-file structural types ─────────────────────────────────────────────
+export type {
+	EntityDef,
+	EntityReference,
+	NumberSequenceDef,
+	PeriodConfig,
+	AccumulationConfig,
+	SignConfig,
+	LedgerRegistryEntry,
+	TraitCd,
+} from "./entity";
+
+export {
+	dataViewKinds,
+	type DataViewsFile,
+	type DataViewDef,
+	type DataSource,
+	type ViewColumn,
+	type ViewType,
+	type KanbanViewConfig,
+	type CalendarViewConfig,
+	type TreeGridViewConfig,
+	type ListViewConfig,
+	type ListLevelConfig,
+	type DiagramViewConfig,
+} from "./data-views";
+
+export {
+	vizTypes,
+	chartTypes,
+	type ReportsFile,
+	type ReportDef,
+	type ReportLayout,
+	type ReportPanel,
+	type Dataset,
+	type ReportQuery,
+	type ColumnDef,
+	type ParamDef,
+	type VizType,
+} from "./reports";
+
+export type { ManifestDef, ManifestAuthor, ModuleDependency } from "./manifest";
+export type { MenusFile, MenuDef, MenuItemDef, MenuItemType } from "./menus";
+export type { FoldersFile, FolderDef, FolderEntityBinding } from "./folders";
+export type { RolesFile, RoleDef } from "./roles";
+export type { SettingsFile, SettingDef, SettingBaseDatatype } from "./settings";
+export type { JobsFile, JobDef } from "./jobs";
+export type { TriggersFile, TriggerDef, EntityEvent } from "./triggers";
+export type { WebhooksFile, WebhookSubscription, WebhookPayload } from "./webhooks";
+export type { PrintTemplatesFile, PrintTemplateDef, PrintPageSettings, PrintMargins } from "./print-templates";
+export type { SeedDataFile } from "./seed-data";
+export type { ActionsFile, ActionDef, ActionExecutionMode } from "./actions";
+
+// Display flag catalog — the only flags valid on an authored field
+// (entity.schema.json `flags` pattern is ^[VIEMH]*$).
+export const flagDefs: readonly { value: "V" | "I" | "E" | "M" | "H"; label: string }[] = [
+	{ value: "V", label: "Visible" },
+	{ value: "I", label: "Identity" },
+	{ value: "E", label: "Editable" },
+	{ value: "M", label: "Mandatory" },
+	{ value: "H", label: "Hidden" },
+] as const;

package/src/jobs.ts

@@ -0,0 +1,34 @@
+// Scheduled jobs — authoring shape of `logic/jobs.json`. Mirror of jobs.schema.json.
+
+/** A single scheduled-job declaration. */
+export interface JobDef {
+	/** Unique identifier within the module. */
+	code: string;
+	description?: string;
+	/** Action code in this module the scheduler fires. */
+	action: string;
+	/** Five-field cron expression (minute granularity). */
+	schedule: string;
+	/** Static parameters passed to the action as `__params`. */
+	params?: Record<string, unknown>;
+	/** Hard timeout in seconds (1–3600; > 300 requires class 'long_running'). */
+	timeout: number;
+	/** Max parallel runs (1–5; default 1). */
+	concurrency?: number;
+	/** Idempotency key template, e.g. '{job_cd}:{run.month}'. */
+	idempotencyKey?: string;
+	/** Routing class ('long_running' required for any timeout > 300s). */
+	class?: "standard" | "long_running";
+	/** IANA tz name overriding the tenant default. */
+	timeZone?: string;
+	/** Master switch (default true). */
+	enabled?: boolean;
+	/** Soft pause; admin 'trigger now' still works (default false). */
+	paused?: boolean;
+}
+
+/** A `logic/jobs.json` file. */
+export interface JobsFile {
+	/** At most 50 jobs per module. */
+	jobs: JobDef[];
+}

package/src/manifest.ts

@@ -0,0 +1,54 @@
+// Module manifest — authoring shape of `manifest.json`.
+// Mirror of manifest.schema.json.
+
+/** Author block on a manifest. */
+export interface ManifestAuthor {
+	name: string;
+	url?: string;
+}
+
+/** A dependency value: a semver range, or a partial-dep object. */
+export type ModuleDependency = string | { version: string; entities?: string[] };
+
+/** A module package manifest (`manifest.json`). */
+export interface ManifestDef {
+	/** Package format version (currently 1). */
+	packageFormat: number;
+	/** Globally unique module UUID. */
+	moduleId: string;
+	/** Human-readable module code (becomes the schema name and `module_cd`). */
+	code: string;
+	/** 'module' (default) or 'pack' (a dependency bundle owning no entities). */
+	kind?: "module" | "pack";
+	/** Module version (semver). */
+	version: string;
+	/** Database schema version (semver). */
+	dbSchemaVersion: string;
+	displayName: string;
+	description?: string;
+	/** Schema name override (defaults to `code`; system modules use 'dForge'). */
+	schemaName?: string;
+	/** System module flag (cannot be uninstalled, admin-only). Omit for regular modules. */
+	system?: boolean;
+	author?: ManifestAuthor;
+	/** License identifier (e.g. 'proprietary', 'MIT'). */
+	license?: string;
+	/** Module code → semver range or partial-dep object. */
+	dependencies?: Record<string, ModuleDependency>;
+	/** Default audit history mode for this module's entities. */
+	auditHistory?: "none" | "minimal" | "full";
+	/** Entity code → relative path of its JSON file (dotted keys = extensions). */
+	entities?: Record<string, string>;
+	/** Module category for display (e.g. 'Integration', 'Finance'). */
+	category?: string;
+	/** Free-form tags for search/discovery. */
+	tags?: string[];
+	/** Bootstrap icon class (e.g. 'bi-link-45deg'). */
+	icon?: string;
+	/** Non-English locales the package promises to translate. */
+	supportedLocales?: string[];
+	/** Initial creation date (YYYY-MM-DD). Informational. */
+	created?: string;
+	/** Last manifest edit date (YYYY-MM-DD). Informational. */
+	updated?: string;
+}

package/src/menus.ts

@@ -0,0 +1,36 @@
+// Menus — authoring shape of `ui/menus.json`. Mirror of menus.schema.json.
+
+/** Menu item type: V=Data View, D=Document, R=Report, null=folder/section. */
+export type MenuItemType = "V" | "D" | "R" | null;
+
+/** A menu item; folder/section nodes nest children and omit `itemType`. */
+export interface MenuItemDef {
+	itemType?: MenuItemType;
+	/** Data view code (when `itemType` is 'V'). */
+	dataViewCode?: string;
+	/** Document code (when `itemType` is 'D'). */
+	documentCode?: string;
+	/** Report code (when `itemType` is 'R'). */
+	reportCode?: string;
+	orderNum?: number;
+	/** Display text. */
+	label: string;
+	description?: string;
+	/** Bootstrap icon name. */
+	icon?: string;
+	/** Child items keyed by item code (folder/section nodes). */
+	children?: Record<string, MenuItemDef>;
+}
+
+/** A menu (value in the `ui/menus.json` map). */
+export interface MenuDef {
+	label: string;
+	description?: string;
+	/** Folder codes where this menu is available. */
+	folders?: string[];
+	/** Menu items keyed by item code. */
+	items: Record<string, MenuItemDef>;
+}
+
+/** A `ui/menus.json` file: menu code → definition. */
+export type MenusFile = Record<string, MenuDef>;

package/src/print-templates.ts

@@ -0,0 +1,41 @@
+// Print templates — authoring shape of `ui/print_templates.json`.
+// Mirror of print_templates.schema.json.
+
+/** Page margins (CSS lengths, e.g. '15mm'). */
+export interface PrintMargins {
+	top?: string;
+	right?: string;
+	bottom?: string;
+	left?: string;
+}
+
+/** Default page geometry applied when printing from the UI. */
+export interface PrintPageSettings {
+	size?: "A4" | "letter" | "legal";
+	orientation?: "portrait" | "landscape";
+	margins?: PrintMargins;
+}
+
+/**
+ * A print template or snippet (value in the print_templates map).
+ * `type: 'template'` (default) is entity-bound; `type: 'snippet'` is a
+ * module-scoped Liquid partial included via {% include 'module.snippet' %}.
+ * Either `file` or `template` must be set (`file` wins when both are present).
+ */
+export interface PrintTemplateDef {
+	type?: "template" | "snippet";
+	/** Entity code rendered. Required for templates; ignored for snippets. */
+	entityCd?: string;
+	/** Human-readable label shown in the print menu. */
+	description?: string;
+	/** Inline Liquid HTML. */
+	template?: string;
+	/** Relative path under the module's `print_templates/` directory. */
+	file?: string;
+	/** Inline CSS, or a `.css` filename resolved relative to `print_templates/`. */
+	css?: string;
+	pageSettings?: PrintPageSettings;
+}
+
+/** A `ui/print_templates.json` file: template_cd → definition. */
+export type PrintTemplatesFile = Record<string, PrintTemplateDef>;

package/src/reports.ts

@@ -0,0 +1,111 @@
+// Report registries + the authoring shape of a `ui/reports.json` file.
+//
+// `vizTypes` / `chartTypes` are the friendly picker lists; `ReportDef` and
+// friends mirror reports.schema.json so editors/MCP/CLI can build reports.
+
+import type { Filter, SortClause } from "./filter";
+import type { NamedKind } from "./types";
+
+/** Report visualization types. Source: reports.schema.json (`vizType`). */
+export type VizType = "table" | "chart" | "metric" | "pivot";
+
+/** Friendly picker list of report visualization types. */
+export const vizTypes: readonly NamedKind[] = [
+	{ cd: "table", name: "Table" },
+	{ cd: "chart", name: "Chart" },
+	{ cd: "metric", name: "Metric" },
+	{ cd: "pivot", name: "Pivot" },
+] as const;
+
+/** Chart kinds used by report `config.chartType` (curated; rendered via Chart.js). */
+export const chartTypes: readonly NamedKind[] = [
+	{ cd: "bar", name: "Bar" },
+	{ cd: "line", name: "Line" },
+	{ cd: "area", name: "Area" },
+	{ cd: "pie", name: "Pie" },
+	{ cd: "donut", name: "Donut" },
+	{ cd: "scatter", name: "Scatter" },
+	{ cd: "bubble", name: "Bubble" },
+	{ cd: "heatmap", name: "Heatmap" },
+	{ cd: "funnel", name: "Funnel" },
+] as const;
+
+/** A report parameter definition (report- or dataset-level). */
+export interface ParamDef {
+	/** Field type code (see settings for the common list). */
+	fieldTypeCd: string;
+	label?: string;
+	/** Display order in the parameter form (falls back to declaration order). */
+	orderNum?: number;
+	/** Whether the user must provide a value. */
+	required?: boolean;
+	/** Alternate spelling of `required` used by some modules. Prefer `required`. */
+	isRequired?: boolean;
+	/** Default value applied when the user doesn't provide one. */
+	default?: unknown;
+	/** Entity link for lookup-type params. */
+	link?: { entity: string; otherKey?: string };
+	/** Field-type-specific params. */
+	params?: Record<string, unknown>;
+}
+
+/** SQL/entity query for a `datasetType: 'Q'` dataset. */
+export interface ReportQuery {
+	/** Source entity code. */
+	entityCd: string;
+	/** Column codes to select (supports dot navigation: 'customer.name'). */
+	columns?: string[];
+	filter?: Filter;
+	sort?: SortClause[];
+}
+
+/** Per-column metadata override on a dataset. */
+export interface ColumnDef {
+	label?: string;
+	visible?: boolean;
+	width?: number;
+}
+
+/** A report dataset (value in the report's `datasets` map). */
+export interface Dataset {
+	/** Display label (used in panel headings if no `title`). */
+	caption?: string;
+	/** Q = SQL/entity query, S = stored procedure. */
+	datasetType: "Q" | "S";
+	/** Used when `datasetType` is 'Q'. */
+	query?: ReportQuery;
+	/** Used when `datasetType` is 'S'. */
+	procedureName?: string;
+	/** Optional column metadata overrides: field code → override. */
+	columnsDef?: Record<string, ColumnDef>;
+	/** Dataset-level parameters (alternative to report-level `parameters`). */
+	params?: Record<string, ParamDef>;
+}
+
+/** A single visualization panel within the report layout. */
+export interface ReportPanel {
+	vizType: VizType;
+	/** Dataset code (key in the report's `datasets` map). */
+	datasetCd: string;
+	title?: string;
+	/** Viz-type-specific config (chart → { chartType, categoryCol, … }). */
+	config?: Record<string, unknown>;
+}
+
+export interface ReportLayout {
+	panels: ReportPanel[];
+}
+
+/** A single report (value in the `ui/reports.json` map). */
+export interface ReportDef {
+	/** Human-readable report title. */
+	description: string;
+	layout: ReportLayout;
+	/** Dataset code → dataset definition. */
+	datasets: Record<string, Dataset>;
+	/** Report-level parameters (alternative to per-dataset `params`). */
+	parameters?: Record<string, ParamDef>;
+}
+
+/** A `ui/reports.json` file: report code → definition. */
+export type ReportsFile = Record<string, ReportDef>;

package/src/roles.ts

@@ -0,0 +1,12 @@
+// Roles — authoring shape of `security/roles.json`. Mirror of roles.schema.json.
+
+/** A role with its entity rights (value in the roles map). */
+export interface RoleDef {
+	/** Role display name. */
+	description: string;
+	/** Entity code → rights string. Rights: S/I/U/D/C/E (pattern ^[SIUDCE]*$). */
+	rights: Record<string, string>;
+}
+
+/** A `roles.json` file: role code → definition. */
+export type RolesFile = Record<string, RoleDef>;

package/src/seed-data.ts

@@ -0,0 +1,10 @@
+// Seed data — authoring shape of a `seed-data/*.json` file.
+// Mirror of seed_data.schema.json.
+
+/** A seed-data file: records to insert into one entity. */
+export interface SeedDataFile {
+	/** Target entity code. */
+	entityCode: string;
+	/** Records to insert; each is a `column_code → value` map. */
+	records: Record<string, unknown>[];
+}

package/src/settings.ts

@@ -0,0 +1,29 @@
+// Module settings — authoring shape of `settings.json`. Mirror of settings.schema.json.
+
+/** Underlying primitive datatype for a setting. */
+export type SettingBaseDatatype = "string" | "number" | "bool" | "date" | "dateTime" | "time" | "json";
+
+/** A single setting definition (value in the settings map). */
+export interface SettingDef {
+	/** Field type code (must match a `dforge.field_type` code). */
+	fieldTypeCd: string;
+	/** Underlying primitive datatype (older settings declare this explicitly). */
+	baseDatatypeCd?: SettingBaseDatatype;
+	/** Display label (preferred for new settings). */
+	label?: string;
+	/** Display label (older style). Prefer `label`. */
+	description?: string;
+	/** Alternative older label key. Prefer `label`. */
+	desc?: string;
+	/** Default value before the user sets one. */
+	defaultValue?: unknown;
+	/** Formula to evaluate the default (alternative to `defaultValue`). */
+	formula?: string;
+	/** If true, must be set somewhere in the folder chain for install to proceed. */
+	required?: boolean;
+	/** Field-type-specific parameters (dropdown options, min/max, lookup link, …). */
+	params?: Record<string, unknown>;
+}
+
+/** A `settings.json` file: setting code → definition. */
+export type SettingsFile = Record<string, SettingDef>;

package/src/traits.ts

@@ -0,0 +1,127 @@
+// Trait registry — mirror of
+//   server/database/system-modules/metadata/traits.json
+//
+// Traits are authoring shortcuts: adding one to an entity injects a fixed set of
+// fields (and sometimes references) at install time. The visual editor offers
+// these as checkboxes and previews the expanded fields, so authors never
+// hand-write `created_date` / `{entity}_id` etc.
+
+import type { FieldDef, TraitDef } from "./types";
+
+export const traits: readonly TraitDef[] = [
+	{
+		cd: "identity",
+		description: "Primary Key",
+		fields: {
+			"{entity}_id": { dbDatatype: "cuid", flags: "I", isPk: true, isIdentity: true, isNullable: false, orderNum: 1, description: "{Entity} ID" },
+		},
+	},
+	{
+		cd: "audit",
+		description: "Creation and update timestamps",
+		fields: {
+			created_date: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, formula: "NOW()", orderNum: 9901, description: "Created Date" },
+			last_updated: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, formula: "NOW()", orderNum: 9902, description: "Last Updated" },
+		},
+	},
+	{
+		cd: "audit-full",
+		description: "Full audit with user tracking",
+		includes: ["audit"],
+		fields: {
+			created_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9903, description: "Created By User ID" },
+			created_by_user: { columnType: "R", fieldTypeCd: "lookup", flags: "I", orderNum: 9904, description: "Created By", link: { entity: "user", thisKey: "created_by", otherKey: "user_id" } },
+			last_updated_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9905, description: "Last Updated By User ID" },
+			last_updated_by_user: { columnType: "R", fieldTypeCd: "lookup", flags: "I", orderNum: 9906, description: "Last Updated By", link: { entity: "user", thisKey: "last_updated_by", otherKey: "user_id" } },
+		},
+		references: {
+			"FK_{Entity}_CreatedBy": { from: { field: "created_by" }, to: { entity: "user", field: "user_id" } },
+			"FK_{Entity}_LastUpdatedBy": { from: { field: "last_updated_by" }, to: { entity: "user", field: "user_id" } },
+		},
+	},
+	{
+		cd: "soft-delete",
+		description: "Soft delete flag",
+		fields: {
+			active: { dbDatatype: "bool", fieldTypeCd: "checkbox", flags: "", isNullable: false, formula: "true", orderNum: 9910, description: "Active" },
+		},
+	},
+	{
+		cd: "sorting",
+		description: "Display order",
+		fields: {
+			order_num: { dbDatatype: "int4", fieldTypeCd: "number", flags: "VEM", orderNum: 9920, description: "Order" },
+		},
+	},
+	{ cd: "postable", description: "Document posting support (marker trait — actual state managed by A/L columns)", fields: {} },
+	{ cd: "accumulation", description: "Accumulation register (marker trait — config in A-type column params)", fields: {} },
+	{ cd: "ledger", description: "Double-entry ledger (marker trait — config in L-type column params)", fields: {} },
+	{
+		cd: "period",
+		description: "Period entity with key format, closed flag, date range",
+		fields: {
+			period_key: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VEM", isPk: true, isNullable: false, maxLen: 20, orderNum: 1, description: "Period Key" },
+			description: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VEM", maxLen: 100, orderNum: 30, description: "Description" },
+			closed: { dbDatatype: "bool", fieldTypeCd: "checkbox", flags: "VEM", isNullable: false, formula: "false", orderNum: 40, description: "Closed" },
+			start_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VEM", orderNum: 50, description: "Start Date" },
+			end_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VEM", orderNum: 60, description: "End Date" },
+		},
+	},
+] as const;
+
+const byCd = new Map(traits.map((t) => [t.cd, t]));
+
+/** Look up a trait by code. */
+export function getTrait(cd: string): TraitDef | undefined {
+	return byCd.get(cd);
+}
+
+/** Title-case a snake_case entity code for the `{Entity}` template token. */
+function titleCaseEntity(entity: string): string {
+	const local = entity.split(".").pop() ?? entity;
+	return local
+		.split(/[_\s]+/)
+		.filter(Boolean)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join(" ");
+}
+
+function applyTemplate(value: string, entity: string): string {
+	const local = entity.split(".").pop() ?? entity;
+	return value.replace(/\{entity\}/g, local).replace(/\{Entity\}/g, titleCaseEntity(entity));
+}
+
+function templateFields(fields: Record<string, FieldDef>, entity: string): Record<string, FieldDef> {
+	const out: Record<string, FieldDef> = {};
+	for (const [name, def] of Object.entries(fields)) {
+		const key = applyTemplate(name, entity);
+		const next: FieldDef = { ...def };
+		if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
+		out[key] = next;
+	}
+	return out;
+}
+
+/**
+ * Expand a trait (and any traits it includes) into the concrete fields it adds
+ * for `entityName`, with `{entity}` / `{Entity}` tokens resolved. Returns an
+ * empty object for unknown or marker traits. Field order follows include-depth
+ * first, then declaration order; later definitions win on key collisions.
+ */
+export function expandTrait(traitCd: string, entityName: string): Record<string, FieldDef> {
+	const trait = byCd.get(traitCd);
+	if (!trait) return {};
+	const result: Record<string, FieldDef> = {};
+	for (const included of trait.includes ?? []) {
+		Object.assign(result, expandTrait(included, entityName));
+	}
+	Object.assign(result, templateFields(trait.fields, entityName));
+	return result;
+}
+
+/** Expand several traits in order into one merged field map. */
+export function expandTraits(traitCds: readonly string[], entityName: string): Record<string, FieldDef> {
+	const result: Record<string, FieldDef> = {};
+	for (const cd of traitCds) Object.assign(result, expandTrait(cd, entityName));
+	return result;
+}

package/src/triggers.ts

@@ -0,0 +1,27 @@
+// Triggers — authoring shape of `logic/triggers.json`. Mirror of triggers.schema.json.
+
+/** DB event a trigger or webhook watches. */
+export type EntityEvent = "insert" | "update" | "delete" | "status_change" | "any";
+
+/** A single trigger declaration. */
+export interface TriggerDef {
+	/** Trigger code, unique within the module. */
+	code: string;
+	description?: string;
+	/** Entity whose events this watches (cross-module via 'module.entity'). */
+	entity: string;
+	event: EntityEvent;
+	/** Optional `[field]`-syntax formula; trigger fires only when true. */
+	condition?: string;
+	/** Action code to invoke (cross-module form 'module.action' supported). */
+	action: string;
+	/** Static parameters passed to the action, merged with the injected record id. */
+	params?: Record<string, unknown>;
+	/** Run the action in the background after the triggering tx commits (default false). */
+	async?: boolean;
+}
+
+/** A `logic/triggers.json` file. */
+export interface TriggersFile {
+	triggers: TriggerDef[];
+}