IF Commons GitHub

The layers

0001Active

0001-layers · owner if · domain data

The layers

FR-001checkpassing

Governance (layer 1) MUST describe a business domain, its concepts, attributes, relationships and code lists, and the governance of its data (documentation, privacy, security, ownership, quality and requirements), in terms that name no database, no kind of database and no engine; it MUST import nothing but the engine and the kernel.

Enforced (check): .github: cd commons/data && bun run verify — suite/governance-neutral.test.ts: the code of governance names no engine and no part of a relational schema

Proved by: data/suite/governance-neutral.test.ts

Written in: data/governance/api.ts, data/sql/logical/api.ts, data/sql/physical/api.ts

Tests: passed: suite/governance-neutral.test.ts the code of governance names no engine and no part of a relational schema

FR-002checkpassing

A logical schema (layer 2) MUST be made from governance by a projection and MUST know the kind of database (relational) but no engine; it MUST import only governance, the engine and the kernel.

Enforced (check): .github: cd commons/data && bun run verify — suite/logical-project.test.ts: project returns the schema as a value, and a projection is a value given to it or contributed through the engine

Proved by: data/suite/logical-project.test.ts

Written in: data/engine/api.ts, data/governance/api.ts, data/sql/logical/api.ts, data/sql/physical/api.ts

Tests: passed: suite/logical-project.test.ts project returns the schema as a value, and a projection is a value given to it or contribu

Cited by: Governance

FR-003checkpassing

A physical schema (layer 3) MUST be made from a logical schema, a dialect and a target, and MUST be the only layer that knows an engine; it MUST import only the logical schema, governance, the engine and the kernel, and never an extension.

Enforced (check): .github: cd commons/data && bun run verify — suite/physical-neutral.test.ts: the code of the physical core names no engine

Proved by: data/suite/physical-neutral.test.ts

Written in: data/engine/api.ts, data/sql/logical/api.ts, data/sql/physical/api.ts

Tests: passed: suite/physical-neutral.test.ts the code of the physical core names no engine

Cited by: Governance

FR-004checkpassing

Imports MUST point one way: the engine imports nothing of the library; governance imports the engine; the logical schema imports governance and the engine; the physical schema imports the logical schema, governance and the engine; the lifecycle (what changes a database from one physical schema to the next) imports the physical and logical schemas, governance and the engine; a dialect imports the physical and logical schemas, governance and the engine; an extension of SQL imports the lifecycle as well imports the physical and logical schemas, governance and the engine; a model and an extension that needs no database import governance and the engine, and a model may also import the models it requires (0028-modules FR-006), the imports among models making no cycle; and the command line imports any of them. An import that climbs, or reaches around, MUST be a finding.

Enforced (check): .github: cd commons/data && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check, and verify runs the check against its baseline; suite/layers.test.ts: an import that climbs is layers/above, and one that reaches around is layers/around; suite/layers.test.ts: an extension does not import another unit of its own class, and a suite and the command line import what they need

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

Written in: data/engine/api.ts, data/governance/api.ts, data/sql/physical/api.ts, data/tools/layers.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check, and verify runs the check against its ba; passed: suite/layers.test.ts an extension does not import another unit of its own class, and a suite and the command li; passed: suite/layers.test.ts an import that climbs is layers/above, and one that reaches around is layers/around

Cited by: Arca, the party model

FR-005checkpassing

Layers 1 to 3 and the engine MUST import no package but Core (@intellectual-frontiers/core) and this library's own, so that nothing of a host, a driver or an engine reaches them.

Enforced (check): .github: cd commons/data && bun run verify — suite/layers.test.ts: the lower layers import only the kernel and the package, and a driver, a host module or another package is layers/external

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

Written in: data/engine/api.ts, data/governance/api.ts, data/sql/physical/api.ts, data/tools/layers.ts

Tests: passed: suite/layers.test.ts the lower layers import only the kernel and the package, and a driver, a host module or an

Identity and flow

FR-006checkpassing

Every element of governance MUST have an identity that never changes; every element of a logical schema MUST carry the identity of the element it was made from, and every object of a physical schema the identity of the element of the logical schema, so that the links form a graph from a concept to a column to a table.

Enforced (check): .github: cd commons/data && bun run verify — suite/logical-project.test.ts: the schema is plain data whose elements have identities of their own and trace to governance elements; suite/physical-bind.test.ts: every statement carries the logical elements it was made from

Proved by: data/suite/logical-project.test.ts, data/suite/physical-bind.test.ts

Written in: data/engine/api.ts, data/governance/api.ts, data/sql/physical/api.ts

Tests: passed: suite/logical-project.test.ts the schema is plain data whose elements have identities of their own and trace to governan; passed: suite/physical-bind.test.ts every statement carries the logical elements it was made from

FR-007checkpassing

Governance MUST never be silently dropped on its way down: each annotation MUST end as expressed (a constraint, a policy or a comment), carried as data (a table), or named as unexpressed in a report of the flow.

Enforced (check): .github: cd commons/data && bun run verify — suite/documentation.test.ts: the documentation table is made where there is no comment, everywhere, or nowhere, as its setting says

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

Written in: data/engine/api.ts, data/governance/api.ts

Tests: passed: suite/documentation.test.ts the documentation table is made where there is no comment, everywhere, or nowhere, as its

Folders and public surfaces

FR-008checkpassing

Every .ts file of the library MUST belong to exactly one unit of the table the check holds (engine/, governance/, sql/logical/, sql/physical/, sql/lifecycle/, sql/presets/, each folder of models/, extensions/, sql/dialects/ and sql/extensions/, sql/cli/, suite/, examples/, tools/ and the files of the library's root), and a file that belongs to none MUST be a finding.

Enforced (check): .github: cd commons/data && bun run verify — suite/layers.test.ts: every file of the real tree is in a unit, and a file in none is layers/unclassified

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

Written in: data/about.ts, data/engine/api.ts, data/governance/api.ts, data/library.ts, data/tools/layers.ts

Tests: passed: suite/layers.test.ts every file of the real tree is in a unit, and a file in none is layers/unclassified

FR-009checkpassing

The public surface of each layer MUST be one entry of the exports of the library's package.json: ./engine, ./governance, ./sql/logical and ./sql/physical, each the api.ts of its folder; an import by the package's name of a subpath that exports does not name MUST be a finding.

Enforced (check): .github: cd commons/data && bun run verify — suite/layers.test.ts: the four layer entries of exports are the api.ts of their folders, and a subpath exports does not name is layers/private

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

Written in: data/engine/api.ts, data/governance/api.ts, data/sql/logical/api.ts, data/sql/physical/api.ts, data/tools/layers.ts

Tests: passed: suite/layers.test.ts the four layer entries of exports are the api.ts of their folders, and a subpath exports d

FR-010checkpassing

A file of a layer, a model, an extension, a dialect or the command line MUST import a file of another unit by the package's name, through an entry of exports, and MUST NOT import it by a relative path; a relative import that reaches another unit MUST be a finding. The suite, the examples, the tools and the files of the root are the library's own checking, not its layers, and MAY import any file of the library by a relative path.

Enforced (check): .github: cd commons/data && bun run verify — suite/layers.test.ts: a relative import into another unit is layers/relative, and one inside the unit is not

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

Written in: data/tools/layers.ts

Tests: passed: suite/layers.test.ts a relative import into another unit is layers/relative, and one inside the unit is not

The check

FR-011checkpassing

tools/layers.ts MUST find each of the above as data (layers/unclassified, layers/relative, layers/private, layers/external, layers/above, layers/around and layers/cycle), reading every import of every file of the library, relative or by package name; tools/check.ts MUST run it with the trace of the library's sources and tests to these specifications (commons 0015-trace), hold the findings against trace.baseline.txt, and be part of bun run verify.

Enforced (check): .github: cd commons/data && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check, and verify runs the check against its baseline; suite/layers.test.ts: the check reads every form of import and no comment, and gives each finding a key that does not name its line; suite/trace.test.ts: a citation is read against this library's specifications, not commons'

Proved by: data/suite/layers.test.ts, data/suite/trace.test.ts

Written in: data/sql/physical/api.ts, data/tools/check.ts, data/tools/layers.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check, and verify runs the check against its ba; passed: suite/layers.test.ts the check reads every form of import and no comment, and gives each finding a key that doe; passed: suite/trace.test.ts a citation is read against this library's specifications, not commons'

Names

FR-012checkpassing

A name MUST cross the layers as a list of words: governance's names MUST be lower camel case and words MUST split them, the logical schema MUST choose the words of each element of a relational schema, and the physical schema MUST write the words in the case style of its target (0005-naming); a name of governance MUST NOT hold a database's convention.

Enforced (check): .github: cd commons/data && bun run verify — suite/logical-project.test.ts: the columns of every table of the model it replaces are what the words of the attributes and relationships make, the key first; suite/physical-bind.test.ts: the case style writes every name, and a snake case schema is the default

Proved by: data/suite/logical-project.test.ts, data/suite/physical-bind.test.ts

Written in: data/governance/api.ts, data/sql/logical/api.ts

Tests: passed: suite/logical-project.test.ts the columns of every table of the model it replaces are what the words of the attributes a; passed: suite/physical-bind.test.ts the case style writes every name, and a snake case schema is the default

Out of scope

  • What each layer does: governance, the logical schema and the physical schema have specifications of their own; this one says only how they are laid out and what each may import.
  • Layers of another kind of database (a graph, a document store): a later folder beside sql/ would take the same table.
  • Checking the imports of the engine's extensions among themselves beyond FR-004 (requires is specified in 0002-engine).

Edge cases

  • A file of sql/logical/ that imports @intellectual-frontiers/data/sql/physical: layers/above, per FR-004.
  • A file of governance/ that imports @intellectual-frontiers/data/sql/logical: layers/above, per FR-004.
  • A file of one extension that imports another extension's surface: layers/around, per FR-004.
  • A file of models/arca/ that imports @intellectual-frontiers/data/sql/physical: layers/around, per FR-004.
  • A file of sql/physical/ that imports a database driver, or node:fs: layers/external, per FR-005.
  • A file of governance/ that imports ../engine/api.ts: layers/relative, per FR-010.
  • A file that imports @intellectual-frontiers/data/engine/internal, a file exports does not name: layers/private, per FR-009.
  • A .ts file in a folder the table does not know: layers/unclassified, per FR-008.
  • A file of suite/ that imports any unit by package name: allowed, per FR-004.
  • A file of suite/ that imports ../tools/layers.ts by a relative path: allowed, the suite and the tools are the library's own checking, per FR-010.
  • An import that is a comment, or inside a template literal: not read, as the kernel's reader does not read it, per FR-011.

Assumptions

  • The table is the library's own: commons' ladder (commons 0016-ladder) is not used, because the engine and the layers do not fit its rungs without a file for each extension that imports the engine; the layers keep the ladder's rule (a unit relies only on what is below it) and its order of work (governance, then the logical schema, then the physical schema, then extensions).
  • FR-006 and FR-007 are Planned: they are built with governance and the logical schema, and the register says so.
  • A model and an extension that need no database are above governance and below nothing: nothing in the library imports them but the command line.

Open questions

OQ-1open question

Whether an extension of SQL may import a neutral extension through requires (0002-engine), and what its table row then says.

Key entities

  • Layer - governance, the logical schema or the physical schema.
  • Unit - a folder of the table that FR-008 names, with the units it may import.
  • Public surface - an entry of exports, the api.ts of a layer.
  • Finding - what the check says is wrong, with a rule, a file, a line and a key, held against a baseline.

Success criteria

SC-001success criterion

A change that makes a lower layer know a higher one, or a layer know an engine it should not, fails bun run verify and names the file and the rule.

SC-002success criterion

No import by package name escapes the check, which the compiler and the runtimes do not give.

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

Intellectual Frontiers Commons, The layers of GRC, The engine, Governance, Arca, the party model, The logical schema, The physical schema

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