@dforge-core/metadata 0.0.35 → 0.0.37

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.37] — 2026-10-12
+
+### Added
+
+- **`settings.json` `$constraints`:** `SettingConstraintDef` (`{ type: "check", expression, message? }`),
+  the optional `$constraints` map on `SettingsFile` — check constraints across a module's settings,
+  written as SQL over setting codes — and `settingDefsOf(file)`, which returns a file's settings
+  without it. `settings.schema.json` and `translations.schema.json` describe both.
+
+## [0.0.36] — 2026-10-08
+
+### Added
+
+- **Registers, typed and checked:** `RegisterDef` / `RegistersFile` (the authoring shape of
+  `registers.json`), `RegisterBindingParams` (an A / L column's `params` bound to a register),
+  and the installer's rules as functions every tool can share — `checkRegister` /
+  `checkRegisters` for a declaration (per-kind required and refused properties, resource shapes,
+  the accounting and totals rules; with a `RegisterEntityLookup`, the entities it names and the
+  columns they store) and `checkRegisterBinding` for a binding (qualified and declared register,
+  the kind a column type may post to, map keys, unmapped required resources, locked fields, the
+  date column being locked, line and account fields, `headerMap` and `skipPostingWhenEmpty`
+  rules). Issues carry a JSON path, a stable code and a severity, and every rule fails open where
+  the caller can't resolve what is named. Helpers: `registerDimensions`, `registerResources`,
+  `registerCarrier`, `registerResourceShape`, `registerLineMode`, `registerRequiredProps`,
+  `registerRefusedProps`, `isPlainColumnRef`; constants `REGISTER_KINDS`, `REGISTER_CODE`,
+  `REGISTER_COLUMN_NAME`, `REGISTER_TOTALS_PERIODS`.
+
 ## [0.0.35] — 2026-10-07
 
 ### Added

package/dist/index.d.ts

@@ -1553,8 +1553,233 @@ type SettingDef = (SettingDefBase & {
     baseDatatypeCd?: never;
     params?: never;
 });
-/** A `settings.json` file: setting code → definition. */
-type SettingsFile = Record<string, SettingDef>;
+/** A check across a module's settings: SQL over setting codes, as an entity check constraint. */
+interface SettingConstraintDef {
+    type: "check";
+    /** PostgreSQL boolean over setting codes; writing any setting it names re-checks it. */
+    expression: string;
+    message?: string;
+}
+/**
+ * A `settings.json` file: setting code → definition, plus the optional `$constraints`. A
+ * setting code cannot start with `$`, but TypeScript cannot exclude it from the index, so
+ * the index admits the constraints map too.
+ */
+type SettingsFile = {
+    $constraints?: Record<string, SettingConstraintDef>;
+    [settingCd: string]: SettingDef | Record<string, SettingConstraintDef> | undefined;
+};
+/** The settings of a file, without its `$constraints`. */
+declare function settingDefsOf(file: SettingsFile): Record<string, SettingDef>;
+
+/** The four kinds. Each requires and refuses a fixed set of properties. */
+type RegisterKind = "balance" | "turnover" | "info" | "accounting";
+declare const REGISTER_KINDS: readonly RegisterKind[];
+declare const isRegisterKind: (value: unknown) => value is RegisterKind;
+/** Register codes: lowercase letters, digits and underscores, starting with a letter. */
+declare const REGISTER_CODE: RegExp;
+/** A column name as `registers.json` takes one. */
+declare const REGISTER_COLUMN_NAME: RegExp;
+/** How much one cached row of a `totals` cache covers. */
+type RegisterTotalsPeriod = "day" | "month" | "quarter" | "year";
+declare const REGISTER_TOTALS_PERIODS: readonly RegisterTotalsPeriod[];
+/** A measured column of the register: one shared column, or one per side on an accounting register. */
+interface RegisterResourceDef {
+    /** The column, on the state entity / journal / record entity. Not with `debitField` / `creditField`. */
+    field?: string;
+    /** Debit-side column, on an accounting register. Declared with `creditField`. */
+    debitField?: string;
+    creditField?: string;
+    /** Every binding must map it (default true). False for a resource only some writers supply. */
+    required?: boolean;
+    /** Under `recordChangesOnly`: what the resource compares as before any record is in effect. */
+    absentAs?: number | string | boolean;
+    description?: string;
+}
+/** The per-period cache (registers.md §8). */
+interface RegisterTotalsDef {
+    entity: string;
+    period: RegisterTotalsPeriod;
+    /** Column holding the first date of the period a row covers. */
+    periodField: string;
+    /** Account column; required on an accounting register, refused elsewhere. */
+    accountField?: string;
+    /** Which dimensions the cache is grouped by; accounting only; all of them when omitted. */
+    dimensions?: string[];
+    /** Every resource of the register: `inField` + `outField`, or `debitField` + `creditField` on an accounting register. */
+    resources: Record<string, {
+        inField?: string;
+        outField?: string;
+        debitField?: string;
+        creditField?: string;
+    }>;
+}
+/** Where the chart says which analytic each account carries in which slot. */
+interface RegisterCompositionDef {
+    entity: string;
+    account: string;
+    slot: string;
+    analytic: string;
+}
+/** One declaration of `registers.json`. */
+interface RegisterDef {
+    kind: RegisterKind;
+    label?: string;
+    description?: string;
+    /** State table (`balance`) or record table (`info`). */
+    entity?: string;
+    /** Movement / posting entity (`balance` optional, `turnover` and `accounting` required). */
+    journal?: string;
+    /** Journal column stamped +1 / −1 (`balance`, `turnover`). */
+    journalDirection?: string;
+    /** Journal column holding each movement's date. */
+    journalDate?: string;
+    /** Record-entity column holding when a record takes effect (`info`). */
+    period?: string;
+    /** Record-entity jsonb column the writing document is stamped into (`info`); makes the register subordinate. */
+    recorder?: string;
+    recordChangesOnly?: boolean;
+    /** Chart of accounts (`accounting`). */
+    chart?: string;
+    lineMode?: "classic" | "compound";
+    /** Posting column pointing at the chart (classic). */
+    account?: string;
+    debitAccount?: string;
+    creditAccount?: string;
+    /** Analytic slot columns in slot order (classic). */
+    analyticFields?: string[];
+    debitAnalyticFields?: string[];
+    creditAnalyticFields?: string[];
+    composition?: RegisterCompositionDef;
+    /** 1–8 column names: the key of the register, on its carrier. */
+    dimensions: string[];
+    /** Two-sided dimensions of a compound register, with the column per side. */
+    sideDimensions?: Record<string, {
+        debitField: string;
+        creditField: string;
+    }>;
+    resources: Record<string, RegisterResourceDef>;
+    totals?: RegisterTotalsDef;
+    /** `balance`: may the state go below zero (default false). */
+    allowNegative?: boolean;
+    /** `balance`: create the state row on first movement (default true). */
+    autoCreate?: boolean;
+}
+/** `registers.json`: register code → declaration. */
+type RegistersFile = Record<string, RegisterDef>;
+/** A map entry: a column of the row read, or on a compound ledger one column per side. */
+type RegisterMapValue = string | {
+    debit?: string;
+    credit?: string;
+};
+/** `params` of an A / L column bound to a register (registers.md §4). */
+interface RegisterBindingParams {
+    /** `module_cd.register_cd`. */
+    register?: string;
+    /** The bool column recording the posted state, when not the column itself. */
+    stateField?: string;
+    direction?: "increase" | "decrease";
+    /** Per-row direction from a document value, instead of `direction`. */
+    sign?: {
+        field: string;
+        positive?: unknown[];
+        negative?: unknown[];
+    };
+    /** Document column (or path / expression) supplying the journal date. */
+    dateField?: string;
+    dateTrunc?: "day" | "month" | "year";
+    lineEntity?: string;
+    lineField?: string;
+    groupLinesBy?: string[];
+    /** Register dimension or resource name → column of the row read. */
+    map?: Record<string, RegisterMapValue>;
+    /** On a line posting: register name → DOCUMENT column. */
+    headerMap?: Record<string, string>;
+    lockedFields?: string[];
+    lockedLineFields?: string[];
+    skipPostingWhenEmpty?: string[];
+    /** Classic ledger: the line's account column. */
+    accountField?: string;
+    debitAccountField?: string;
+    creditAccountField?: string;
+    periodDimField?: string;
+    /** Analytic kind → line column (classic ledger). */
+    analytics?: Record<string, string>;
+    debitAnalytics?: Record<string, string>;
+    creditAnalytics?: Record<string, string>;
+    movementMapping?: Record<string, string>;
+    /** Inline restatement of a register; refused alongside `register`. */
+    registries?: unknown;
+}
+
+type Raw = Record<string, unknown>;
+/** A declaration's dimension names, only the ones that are strings. */
+declare const registerDimensions: (def: RegisterDef | Raw) => string[];
+/** A declaration's resources in file order, each with its definition object. */
+declare const registerResources: (def: RegisterDef | Raw) => Array<{
+    name: string;
+    def: Raw;
+}>;
+/** The entity the dimensions, resources and stamps are columns of. */
+declare function registerCarrier(def: RegisterDef | Raw): string | undefined;
+/** How a resource names its column: one shared column, or one per side. */
+declare const registerResourceShape: (resource: RegisterResourceDef | Raw) => "field" | "split";
+declare const registerLineMode: (def: RegisterDef | Raw) => "classic" | "compound";
+declare const registerRefusedProps: (kind: RegisterKind) => readonly string[];
+declare const registerRequiredProps: (kind: RegisterKind) => readonly string[];
+
+type IssuePath = Array<string | number>;
+/** One finding, addressed by a JSON path relative to what was checked. */
+interface RegisterIssue {
+    path: IssuePath;
+    message: string;
+    /** `error`: install refuses it. `warning`: worth a look. */
+    severity: "error" | "warning";
+    /** Stable id, namespaced `registers/*` for a declaration and `entity/register-*` for a binding. */
+    code: string;
+}
+
+/**
+ * What an entity a declaration names looks like, as far as the caller knows.
+ * `columns` is left undefined when they can't be listed (a dependency known
+ * only from its contract), and no column rule runs against it.
+ */
+interface RegisterEntityInfo {
+    columns?: Iterable<string>;
+}
+/**
+ * Resolves an entity code as `registers.json` writes it — bare for the module's
+ * own, `module.entity` for another's. Returns `null` when nothing can be known
+ * (the module named isn't available: the rule stands down) and `undefined` when
+ * the module is known and has no such entity.
+ */
+type RegisterEntityLookup = (code: string) => RegisterEntityInfo | null | undefined;
+
+/**
+ * Check one declaration against the schema's per-kind rules and the installer's
+ * — paths relative to the declaration. With a lookup, the entities it names are
+ * checked to exist and the columns it names to be stored on them.
+ */
+declare function checkRegister(raw: unknown, lookup?: RegisterEntityLookup): RegisterIssue[];
+/**
+ * Check a whole `registers.json`: every declaration (paths prefixed by its
+ * code), plus the codes themselves and the file's limits.
+ */
+declare function checkRegisters(file: unknown, lookup?: RegisterEntityLookup): RegisterIssue[];
+
+/** What a binding is checked against: the parts of a declaration it has to agree with. */
+type RegisterBindingTarget = Pick<RegisterDef, "kind" | "dimensions" | "resources" | "recorder" | "lineMode" | "sideDimensions">;
+/** A reference path (`ref.column`), an expression (`=…`) or a quoted constant — not a plain column. */
+declare const isPlainColumnRef: (value: string) => boolean;
+/**
+ * Check an A / L column's `params` against the register it binds — paths
+ * relative to `params`. `register` is the resolved declaration, `undefined`
+ * when the module named declares no such register, `null` when that module
+ * can't be seen (every rule that needs the declaration then stands down).
+ */
+declare function checkRegisterBinding(columnType: "A" | "L", rawParams: unknown, register: RegisterBindingTarget | null | undefined, options?: {
+    moduleCode?: string;
+}): RegisterIssue[];
 
 /** A single scheduled-job declaration. */
 interface JobDef {
@@ -1791,4 +2016,4 @@ declare const flagDefs: readonly {
     label: string;
 }[];
 
-export { AGG_TYPE_LIST, type AccumulationConfig, AggType, type AlignType, type AuditHistoryLevel, type BaseDatatypeCd, type CalendarViewConfig, type CardFieldDef, type CardFieldEntry, type CardLayout, type CardLayoutDef, type CardLayoutsFile, type CardSection, type CardSetConfig, type CardTabRef, type ColumnDef, type ColumnGroupSection, type ColumnTypeCd, type ColumnTypeDef, DEP_COLUMN_TYPES, type DataSource, type DataViewDef, type DataViewsFile, type Dataset, type DepColumn, type DepColumnMode, type DepColumnType, type DepEntity, type DepProvenance, type DepProvenanceKind, type DepsFile, type DeriveOptions, type DiagramDef, type DiagramDetail, type DiagramEntity, type DiagramFile, type DiagramRelation, type DiagramViewConfig, type DomainDef, type DomainsFile, type EntityDef, type EntityEvent, type EntityReference, type EntityViewColumnDef, type EntityViewDef, FILTER_GROUP_OPERATORS, FILTER_OPERATORS, type FieldDef, type FieldLink, type FieldOption, type FieldTypeCd, type FieldTypeDef, type Filter, type FilterCondition, type FilterGroup, type FilterGroupOperator, type FilterOperator, type FlagCd, type FolderDef, type FolderEntityBinding, type FoldersFile, type JobDef, type JobsFile, type KanbanViewConfig, type LedgerRegistryEntry, type ListLevelConfig, type ListViewConfig, type ManifestAuthor, type ManifestDef, type MenuDef, type MenuItemDef, type MenuItemType, type MenusFile, type ModuleDependency, type ModuleFeature, NUMERIC_TOTAL, type NamedKind, type NumberSequenceDef, type ParamDef, type ParamDefBase, type PeriodConfig, type PrintMargins, type PrintPageSettings, type PrintTemplateDef, type PrintTemplatesFile, type ReportDef, type ReportEntityAttachment, type ReportLayout, type ReportPanel, type ReportQuery, type ReportsFile, type RoleDef, type RolesFile, type SeedDataFile, type SeedDataRepeat, type SetSection, type SettingBaseDatatype, type SettingDef, type SettingsFile, type SignConfig, type SortClause, type SpColumnDef, type SpParamDef, type StoredProcedureDef, type StoredProceduresFile, type TabGroupSection, type TraitCd, type TraitDef, type TraitFieldConflict, type TraitsFile, type TranslatedAction, type TranslatedEntity, type TranslatedMenu, type TranslatedOption, type TranslatedReport, type TranslatedWithOptions, type TranslationsFile, type TreeGridViewConfig, type TriggerDef, type TriggersFile, type ViewColumn, type ViewType, type VizType, type WebhookPayload, type WebhookSubscription, type WebhooksFile, baseDatatypes, baseToDbDatatype, chartTypes, columnTypes, dataViewKinds, defaultParams, deriveBaseDatatype, deriveDbDatatype, expandTrait, expandTraits, fieldTypeCds, fieldTypes, fieldTypesByColumnType, flagDefs, getColumnType, getFieldType, getIdentityKeys, getLinks, getPrimaryKeys, getTrait, isFieldTypeCd, traitFieldConflicts, traits, vizTypes };
+export { AGG_TYPE_LIST, type AccumulationConfig, AggType, type AlignType, type AuditHistoryLevel, type BaseDatatypeCd, type CalendarViewConfig, type CardFieldDef, type CardFieldEntry, type CardLayout, type CardLayoutDef, type CardLayoutsFile, type CardSection, type CardSetConfig, type CardTabRef, type ColumnDef, type ColumnGroupSection, type ColumnTypeCd, type ColumnTypeDef, DEP_COLUMN_TYPES, type DataSource, type DataViewDef, type DataViewsFile, type Dataset, type DepColumn, type DepColumnMode, type DepColumnType, type DepEntity, type DepProvenance, type DepProvenanceKind, type DepsFile, type DeriveOptions, type DiagramDef, type DiagramDetail, type DiagramEntity, type DiagramFile, type DiagramRelation, type DiagramViewConfig, type DomainDef, type DomainsFile, type EntityDef, type EntityEvent, type EntityReference, type EntityViewColumnDef, type EntityViewDef, FILTER_GROUP_OPERATORS, FILTER_OPERATORS, type FieldDef, type FieldLink, type FieldOption, type FieldTypeCd, type FieldTypeDef, type Filter, type FilterCondition, type FilterGroup, type FilterGroupOperator, type FilterOperator, type FlagCd, type FolderDef, type FolderEntityBinding, type FoldersFile, type JobDef, type JobsFile, type KanbanViewConfig, type LedgerRegistryEntry, type ListLevelConfig, type ListViewConfig, type ManifestAuthor, type ManifestDef, type MenuDef, type MenuItemDef, type MenuItemType, type MenusFile, type ModuleDependency, type ModuleFeature, NUMERIC_TOTAL, type NamedKind, type NumberSequenceDef, type ParamDef, type ParamDefBase, type PeriodConfig, type PrintMargins, type PrintPageSettings, type PrintTemplateDef, type PrintTemplatesFile, REGISTER_CODE, REGISTER_COLUMN_NAME, REGISTER_KINDS, REGISTER_TOTALS_PERIODS, type RegisterBindingParams, type RegisterBindingTarget, type RegisterCompositionDef, type RegisterDef, type RegisterEntityInfo, type RegisterEntityLookup, type RegisterIssue, type RegisterKind, type RegisterMapValue, type RegisterResourceDef, type RegisterTotalsDef, type RegisterTotalsPeriod, type RegistersFile, type ReportDef, type ReportEntityAttachment, type ReportLayout, type ReportPanel, type ReportQuery, type ReportsFile, type RoleDef, type RolesFile, type SeedDataFile, type SeedDataRepeat, type SetSection, type SettingBaseDatatype, type SettingConstraintDef, type SettingDef, type SettingsFile, type SignConfig, type SortClause, type SpColumnDef, type SpParamDef, type StoredProcedureDef, type StoredProceduresFile, type TabGroupSection, type TraitCd, type TraitDef, type TraitFieldConflict, type TraitsFile, type TranslatedAction, type TranslatedEntity, type TranslatedMenu, type TranslatedOption, type TranslatedReport, type TranslatedWithOptions, type TranslationsFile, type TreeGridViewConfig, type TriggerDef, type TriggersFile, type ViewColumn, type ViewType, type VizType, type WebhookPayload, type WebhookSubscription, type WebhooksFile, baseDatatypes, baseToDbDatatype, chartTypes, checkRegister, checkRegisterBinding, checkRegisters, columnTypes, dataViewKinds, defaultParams, deriveBaseDatatype, deriveDbDatatype, expandTrait, expandTraits, fieldTypeCds, fieldTypes, fieldTypesByColumnType, flagDefs, getColumnType, getFieldType, getIdentityKeys, getLinks, getPrimaryKeys, getTrait, isFieldTypeCd, isPlainColumnRef, isRegisterKind, registerCarrier, registerDimensions, registerLineMode, registerRefusedProps, registerRequiredProps, registerResourceShape, registerResources, settingDefsOf, traitFieldConflicts, traits, vizTypes };