@dforge-core/metadata 0.0.34 → 0.0.36

package/CHANGELOG.md

@@ -7,6 +7,51 @@ and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **Domain-backed stored-procedure result columns:** `stored_procedures.schema.json` and
+  `SpColumnDef` accept `domain`; the domain supplies `fieldTypeCd`, `baseDatatypeCd` and
+  `params`, so a status a report returns no longer repeats the entity's option list.
+- **`entity.schema.json`:** an `A` column posting from lines takes `groupLinesBy` — line
+  columns whose distinct values each post one movement instead of one per line, with `map`
+  read over the grouped columns plus the document.
+- **`entity.schema.json`:** a binding's `map`, `headerMap` and `dateField` value may be an
+  expression — a string starting with `=` holding an `F`-column formula over the row, with
+  one-hop `[ref].[column]` reads.
+- **`entity.schema.json`:** an `A` binding takes `dateTrunc` (`day`, `month`, `year`), which
+  takes the `dateField` value back to the start of that period.
+- **`registers.schema.json`:** a register takes `label`, translated under the new
+  `registers` section of `translations.schema.json`.
+- **`registers.schema.json`:** an `info` register with a `recorder` takes
+  `recordChangesOnly`, and its resources take `absentAs` — what a resource compares as
+  before any record is in effect.
+
+### Changed
+
+- **`entity.schema.json`:** an index is typed — `fields` (required) plus an optional `using`
+  (`btree`, `hash`, `gin`, `gist`, `brin`). Any other key, `columns` among them, is refused;
+  the installer used to skip such an index without a word.
+
 ## [0.0.34] — 2026-10-06
 
 ### Added

package/dist/index.d.ts

@@ -1134,6 +1134,13 @@ interface SpColumnDef {
     width?: number;
     /** Control parameters, the same shape an entity column's `params` takes. */
     params?: Record<string, unknown>;
+    /**
+     * Reusable column domain supplying the control, datatype and option list.
+     * Unqualified resolves within this module, then tenant-created domains;
+     * `module_cd.domain_cd` binds to that module. Mutually exclusive with
+     * `fieldTypeCd`, `baseDatatypeCd` and `params`.
+     */
+    domain?: string;
 }
 
 /** Author block on a manifest. */
@@ -1549,6 +1556,215 @@ type SettingDef = (SettingDefBase & {
 /** A `settings.json` file: setting code → definition. */
 type 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 {
     /** Unique identifier within the module. */
@@ -1784,4 +2000,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 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, traitFieldConflicts, traits, vizTypes };