IF Commons GitHub

Integrations layers

0001Active

0001-integrations-layers · owner if · domain commons

The layers

FR-001checkpassing

The library MUST be arranged as the units of one table, and every file of it MUST be in exactly one unit: src/governance/ (layer 1), src/logical/ (layer 2), one folder under src/physical/ for each adapter (http, transport), one folder under src/surfaces/ for each surface (headless), suite/, tools/ and the files of the root; a file in none MUST be a finding (layers/unclassified).

Enforced (check): .github: cd commons/integrations && 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: integrations/suite/layers.test.ts

Written in: integrations/src/logical/mod.ts, integrations/src/mod.ts, integrations/src/physical/http/mod.ts

Tests: passed: suite/layers.test.ts the shared checker finds nothing in the real tree, and the table's entries are the package; passed: suite/layers.test.ts a file in no unit is layers/unclassified

FR-002checkpassing

Imports MUST point one way: governance imports nothing of the library; the logical layer imports governance; a physical adapter imports the logical layer and governance and never another adapter; a surface imports the adapters, the logical layer and governance. An import that climbs or reaches around MUST be a finding (layers/above, layers/around), and a unit MUST reach another only by the package's name through an entry of exports (layers/relative, layers/private).

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: below may not import above, and a unit reaches another only through exports

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

Written in: integrations/src/physical/http/mod.ts

Tests: passed: suite/layers.test.ts the shared checker finds nothing in the real tree, and the table's entries are the package; passed: suite/layers.test.ts below may not import above, and a unit reaches another only through exports

FR-003checkpassing

Governance and the logical layer MUST import no package but Core; only a physical adapter MUST reach a network (Net), and each adapter and surface MUST have a row of the table naming the packages it may import (layers/external), so that no vendor, no framework and no host reaches a layer below.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: each unit imports only what its row allows, and the pure layers import Core alone

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

Written in: integrations/src/physical/http/mod.ts

Tests: passed: suite/layers.test.ts each unit imports only what its row allows, and the pure layers import Core alone

FR-004checkpassing

The core MUST name no vendor and no framework: no file of governance or of the logical layer MUST name a cloud, a SaaS product, a code host, an EHR or a clearinghouse; a vendor is a plugin package (0008-integrations-plugins).

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: no source of the two pure layers names a vendor

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

Tests: passed: suite/layers.test.ts no source of the two pure layers names a vendor

The check and the package

FR-005checkpassing

tools/check.ts MUST run the trace of the sources and tests to these specifications (commons 0015-trace), beside the shared layers checker in verify, hold the findings against trace.baseline.txt, which only shrinks, and be part of bun run verify.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check

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

Written in: integrations/tools/check.ts

Tests: passed: suite/layers.test.ts the shared checker finds nothing in the real tree, and the table's entries are the package

FR-006checkpassing

The public surface MUST be the entries of exports: ., ./governance, ./logical, ./http, ./transport and ./headless, and a vendor adapter or a standard MUST be a separate package of commons that imports them by name.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: the table's entries are the package's exports

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

Tests: passed: suite/layers.test.ts the shared checker finds nothing in the real tree, and the table's entries are the package

FR-007checkpassing

The library MUST declare its table of layers as the field kanon of its manifest library.ts (commons 0033-kanon FR-010) and its verify MUST run the shared checker of @intellectual-frontiers/kanon (bun ../kanon/src/check.ts); the library keeps no checker of its own.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: the table is read from the manifest and verify runs the shared checker

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

Tests: passed: suite/layers.test.ts the shared checker finds nothing in the real tree, and the table's entries are the package

FR-008checkpassing

The library MUST declare itself with a manifest (library.ts, release.ts, about.ts) and be published as compiled ESM with declarations, with exports conditions types, bun and default (commons 0032-libraries-by-concern).

Enforced (check): .github: cd commons/integrations && bun run verify — suite/layers.test.ts: the manifest agrees with the package

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

Written in: integrations/about.ts, integrations/library.ts, integrations/tools/pack.ts

Tests: passed: suite/layers.test.ts the manifest agrees with the package

Acceptance scenarios

  1. Given a file of src/logical/ that imports @intellectual-frontiers/integrations/http, When the check runs, Then layers/above is found, per FR-002.
  2. Given a file of src/governance/ that imports Net, When the check runs, Then layers/external is found, per FR-003.
  3. Given a folder src/physical/ftp/ with no row, When the check runs, Then its files are layers/unclassified, per FR-001.
  4. Given a source of governance that names a vendor, When the vendor check runs, Then it is a finding, per FR-004.

Out of scope

  • The shared checker of commons/kanon: switched to when it lands (FR-007).
  • Vendor and standards packages: they have their own folders and manifests.

Edge cases

  • A file of suite/ that imports a unit by a relative path: allowed, the suite and the tools are the library's own checking, per FR-002.
  • An import that is a comment: not read, per FR-005.

Assumptions

  • The pattern is Kanon's: governance, then logical, then physical, each importing only below.

Open questions

  • None.

Key entities

  • Unit - a folder of the table with a class and a row of allowed packages.
  • Adapter - a folder of src/physical/ that reaches a network.
  • Surface - a folder of src/surfaces/.

Success criteria

SC-001success criterion

A change that makes a lower layer know a higher one, or a pure layer know a network or a vendor, fails bun run verify and names the file and the rule.

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

Integrations

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