IF Commons GitHub

Modules

0028Active

0028-modules · owner if · domain data

Defining and composing

FR-001checkpassing

defineModule MUST make a module from a name, a definition, the names of the modules it requires, concepts and code lists, and moduleOf MUST make one from a domain that is already valid (Arca), so that a model written as a domain is a module without change; a module MUST be a frozen value that is not validated until it is composed.

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: a project composes the modules it lists into one domain, and a module that is not listed has no table

Proved by: data/suite/modules.test.ts

Written in: data/governance/module.ts

Tests: passed: suite/modules.test.ts a project composes the modules it lists into one domain, and a module that is not listed h

FR-002checkpassing

composeModules MUST make one domain, named and defined by the project, from the modules the project lists, validated as domain validates (names, identifiers, relationships and code lists resolved among all the concepts and code lists of the listed modules), and MUST give errors as values for a required module that is not listed, a cycle among modules, two modules with one name, a concept or code list that two modules both have, and the errors of the domain.

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: a project composes the modules it lists into one domain, and a module that is not listed has no table; suite/modules.test.ts: a required module that is not listed, a cycle, two modules with one name, a concept twice, a reference sideways and the errors of the domain are errors as values

Proved by: data/suite/modules.test.ts

Written in: data/governance/module.ts

Tests: passed: suite/modules.test.ts a project composes the modules it lists into one domain, and a module that is not listed h; passed: suite/modules.test.ts a required module that is not listed, a cycle, two modules with one name, a concept twice,

FR-003checkpassing

A concept of a module MUST refer (by a relationship or a code attribute) only to concepts and code lists of itself or of a module it requires, directly or through the modules those require; a reference to a listed module that it does not require MUST be an error value naming the module, the concept and what it refers to.

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: a required module that is not listed, a cycle, two modules with one name, a concept twice, a reference sideways and the errors of the domain are errors as values

Proved by: data/suite/modules.test.ts

Written in: data/governance/module.ts

Tests: passed: suite/modules.test.ts a required module that is not listed, a cycle, two modules with one name, a concept twice,

FR-004checkpassing

The domain MUST hold the concepts and code lists of the listed modules in the order of the requirements (a module after those it requires, otherwise as listed), and MUST hold nothing of a module that is not listed, so that projecting it makes no table of that module.

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: a project composes the modules it lists into one domain, and a module that is not listed has no table

Proved by: data/suite/modules.test.ts

Written in: data/governance/module.ts

Tests: passed: suite/modules.test.ts a project composes the modules it lists into one domain, and a module that is not listed h

FR-005checkpassing

withRequired MUST give, from the modules that exist and the names a project wants, the modules to compose: those and everything they require, in the order of the requirements, as a plain list the project can read, or an error value for a name that no module has.

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: withRequired gives the modules wanted and everything they require, in the order of the requirements, and a name no module has is an error as a value

Proved by: data/suite/modules.test.ts

Written in: data/governance/module.ts

Tests: passed: suite/modules.test.ts withRequired gives the modules wanted and everything they require, in the order of the req

The layers

FR-006checkpassing

A model MAY import another model through its entry of exports (a module imports the modules it requires); the imports among models MUST be acyclic, and tools/layers.ts MUST report a cycle among models as a finding (layers/cycle).

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: a model may import the models it requires, and a cycle among models is a finding

Proved by: data/suite/modules.test.ts

Tests: passed: suite/modules.test.ts a model may import the models it requires, and a cycle among models is a finding

Cited by: The layers

FR-008checkpassing

A module MAY name the subject it applies to (subject, the id of one of SUBJECTS: parties, identity, pipelines, meaning, operations, project), and where it names none it MUST take the subject the library gives its own name; subjectOf MUST give the subject of a module, and describeModels MUST carry it on each described model so that the models can be grouped by what they apply to.

Enforced (check): .github: cd commons/data && bun run verify — suite/modules.test.ts: every module of the library applies to a subject, one of the six, and a described model carries it; a module that names its own subject keeps it

Proved by: data/suite/modules.test.ts

Written in: data/governance/subjects.ts

Tests: passed: suite/modules.test.ts every module of the library applies to a subject, one of the six, and a described model ca

Cited by: governance/subjects, Data

Out of scope

  • Registering modules with the engine's contribution points: modules are plain values; a project passes the list.
  • A schema of a module's own in the database: one namespace, with the collision check (0007).
  • Removing a module from a database: a plan of destructive steps, with quarantine (0015).
  • Tenant scope as an overlay of the composition: a later specification.

Edge cases

  • A module with no required module: it stands alone, per FR-001.
  • A project that lists a module twice: an error value, per FR-002.
  • A module that refers to a concept of a peer it does not require, even one that is listed: an error value, per FR-003.

Assumptions

  • A module's concepts are values shared by the modules that require it (Arca's person is one object).
  • The composed domain's name is the project's, so that identities of elements are the project's.

Open questions

OQ-1open question

Whether modules are also contributions of the engine, so that compose of extensions gives the list.

Key entities

  • Module - a subject area: its name, what it requires, its concepts and code lists.
  • Composition - the domain made of the modules a project lists.

Success criteria

SC-001success criterion

A project adopts the subject areas it needs and no table of any other is made.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

governance/module, governance/subjects, Data, The layers, Arca tenancy, Identity

Titles, headings, exports, tables, columns and requirements. Esc closes.