IF Commons GitHub

The engine

0002Active

0002-engine · owner if · domain data

Contribution points

FR-001checkpassing

The engine MUST import nothing of the library and nothing but the kernel; it MUST declare no contribution point of a layer, so that a layer declares its own with the engine's mechanism and the engine does not know the layers.

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; suite/layers.test.ts: the engine of the real tree imports nothing of the library and only the kernel by package name

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

Written in: data/engine/point.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; passed: suite/layers.test.ts the engine of the real tree imports nothing of the library and only the kernel by package

FR-002checkpassing

A contribution point MUST be a typed, named value (point<T>(name)), where T is what an extension contributes and the name has a namespace and a name (governance.vocabulary); a name with no namespace MUST NOT compile.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine.test.ts: a point carries its name and is frozen, and a name with no namespace does not compile

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

Written in: data/engine/point.ts

Tests: passed: suite/engine.test.ts a point carries its name and is frozen, and a name with no namespace does not compile

Cited by: engine/point, Data

The manifest

FR-003checkpassing

An extension MUST be one typed value, a manifest made by defineExtension: its identifier (a branded ExtensionId: lower-case words joined by - or .), its version, the version of the engine's contract it was written for, the extensions it requires, what it contributes (each made by contribute(point, value)), the handles it uses, and an optional activate function; it MUST be TypeScript, never YAML, XML or JSON.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-manifest.test.ts: an identifier is lower-case words joined by - or ., and anything else is an error value; suite/engine-manifest.test.ts: a manifest is frozen data with the engine's contract and empty lists by default; suite/engine-manifest.test.ts: a lazy entry holds what the engine must know before it loads, and its loader

Proved by: data/suite/engine-manifest.test.ts

Written in: data/engine/id.ts, data/engine/manifest.ts

Tests: passed: suite/engine-manifest.test.ts a lazy entry holds what the engine must know before it loads, and its loader; passed: suite/engine-manifest.test.ts a manifest is frozen data with the engine's contract and empty lists by default; passed: suite/engine-manifest.test.ts an identifier is lower-case words joined by - or ., and anything else is an error value

Cited by: engine/id, engine/manifest, Data

FR-004checkpassing

A manifest's contributions MUST be typed by the point they fill, so that a contribution of another type to a point does not compile.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-manifest.test.ts: a contribution is typed by its point, and a value of another type does not compile

Proved by: data/suite/engine-manifest.test.ts

Written in: data/engine/manifest.ts

Tests: passed: suite/engine-manifest.test.ts a contribution is typed by its point, and a value of another type does not compile

Composition

FR-005checkpassing

A project MUST compose its extensions by passing them to compose, an explicit list; the engine MUST NOT scan folders for extensions and MUST NOT register an extension by its being imported.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-compose.test.ts: an extension defined in an imported module is in no composition until the project lists it

Proved by: data/suite/engine-compose.test.ts

Written in: data/engine/compose.ts

Tests: passed: suite/engine-compose.test.ts an extension defined in an imported module is in no composition until the project lists it

Cited by: engine/compose, Data

FR-006checkpassing

compose MUST put the extensions in an order that satisfies requires, the order the project listed them where requires does not decide, and MUST return as values (never by throwing), all together, each missing extension, each cycle, each contract version the engine does not have, each handle used and not provided, and each identifier that two extensions claim.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-compose.test.ts: the order satisfies requires, and keeps the project's order where requires does not decide; suite/engine-compose.test.ts: a duplicate, a missing extension, a cycle and a contract the engine lacks are returned as values, and all together; suite/engine-compose.test.ts: a handle that an extension uses and the project did not provide is returned, and one that it provided is not

Proved by: data/suite/engine-compose.test.ts

Written in: data/engine/compose.ts

Tests: passed: suite/engine-compose.test.ts a handle that an extension uses and the project did not provide is returned, and one that ; passed: suite/engine-compose.test.ts a duplicate, a missing extension, a cycle and a contract the engine lacks are returned as ; passed: suite/engine-compose.test.ts the order satisfies requires, and keeps the project's order where requires does not decide

FR-007checkpassing

What a layer needs of its extensions MUST reach it as a value the project passes in (the contributions of a point, in order), not as a registry the layer looks into.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-compose.test.ts: what a layer needs reaches it as the contributions of a point, in the order of the composition

Proved by: data/suite/engine-compose.test.ts

Written in: data/engine/compose.ts

Tests: passed: suite/engine-compose.test.ts what a layer needs reaches it as the contributions of a point, in the order of the composi

Activation

FR-008checkpassing

An extension MAY be given as a lazy entry (lazyExtension: identifier, version, contract, requires, the events that start it, and load, a thunk such as () => import(...)), and the engine MUST load and activate it only when fire is given one of its events, after the extensions it requires; an extension activated twice, even at once, MUST be activated once; a lazy extension's contributions MUST appear only after it is activated; a load whose manifest has another identifier, and an activate or a load that fails, MUST be returned as values.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-activation.test.ts: start activates the extensions that are not lazy, in order, once each; suite/engine-activation.test.ts: a lazy extension is loaded and activated only when its event is fired, and its contributions appear then; suite/engine-activation.test.ts: two events at once load and activate a lazy extension once; suite/engine-activation.test.ts: a lazy extension is activated after what it requires, even what is lazy or not yet started; suite/engine-activation.test.ts: a load with another identifier, a load that fails and an activate that throws come back as values, and stay failed; suite/engine-manifest.test.ts: a lazy entry holds what the engine must know before it loads, and its loader

Proved by: data/suite/engine-activation.test.ts, data/suite/engine-manifest.test.ts

Written in: data/engine/compose.ts, data/engine/manifest.ts

Tests: passed: suite/engine-activation.test.ts a lazy extension is activated after what it requires, even what is lazy or not yet started; passed: suite/engine-activation.test.ts a lazy extension is loaded and activated only when its event is fired, and its contributio; passed: suite/engine-activation.test.ts a load with another identifier, a load that fails and an activate that throws come back as; passed: suite/engine-activation.test.ts start activates the extensions that are not lazy, in order, once each; passed: suite/engine-activation.test.ts two events at once load and activate a lazy extension once and 1 more

FR-009checkpassing

activate MUST receive a context whose use(handle) gives only a handle the manifest declared in uses, and only what the project provided for it (provide(handle, value)); any other is an error value (undeclared, unprovided). A handle is a typed, named value of the engine's mechanism (handle<T>(name)) and the engine defines none of the layers' handles (the trace graph, the statements to emit, the files to write: each layer defines its own), so that an extension has no reach beyond what it declared; this is a discipline, not a sandbox, and the check of FR-004 in 0001-layers is what keeps an extension to the public surfaces.

Enforced (check): .github: cd commons/data && bun run verify — suite/engine-activation.test.ts: activate can use only the handles the manifest declared and the project provided, typed by the handle; suite/engine-activation.test.ts: a lazy extension that declares a handle the project did not provide is not activated, and says which; suite/engine-compose.test.ts: a handle that an extension uses and the project did not provide is returned, and one that it provided is not

Proved by: data/suite/engine-activation.test.ts, data/suite/engine-compose.test.ts

Written in: data/engine/compose.ts, data/engine/handle.ts

Tests: passed: suite/engine-activation.test.ts a lazy extension that declares a handle the project did not provide is not activated, and ; passed: suite/engine-activation.test.ts activate can use only the handles the manifest declared and the project provided, typed by; passed: suite/engine-compose.test.ts a handle that an extension uses and the project did not provide is returned, and one that

Cited by: engine/compose, engine/handle, Data

Out of scope

  • What any extension does: each has a specification of its own.
  • Sandboxing code that runs in the same process: not provided, FR-009 says so.
  • Finding extensions installed by a package manager: a project lists what it uses.

Edge cases

  • point("vocabulary") with no namespace: does not compile, per FR-002.
  • A manifest that contributes a string to a point of terms: does not compile, per FR-004.
  • Two extensions that both claim the identifier privacy: compose returns the conflict, per FR-006.
  • An extension that requires one that is not in the list: compose returns the missing one, per FR-006.
  • Extensions that require each other: compose returns the cycle, per FR-006.
  • A lazy extension fired by two events at once: it is loaded and activated once, per FR-008.
  • A lazy extension whose load returns a manifest with another identifier: returned as a value, and nothing is activated, per FR-008.
  • An activate that throws: returned as a value that names the extension, which is not active, per FR-008.
  • An extension that calls use on a handle it did not declare: undeclared, per FR-009.
  • An extension that declares a handle the project did not provide: compose returns it, per FR-006.
  • A module that registers an extension at import time: no registry exists for it to reach, per FR-005.

Assumptions

  • Every requirement here is built by phase 2 of the library, and none is left Planned.
  • An activation that failed stays failed in its composition: it is not tried again; a project that wants another try composes again.
  • The contract's version is a small integer the engine raises when it breaks a manifest, not a semantic version.

Open questions

OQ-1open question

The events an extension may be activated by, which the layers declare (onDialect:postgres, onGenerate:rust).

Key entities

  • Contribution point - a named, typed place a layer lets extensions fill.
  • Manifest - the typed value that is an extension.
  • Composition - the ordered, checked list of extensions a project uses.
  • Handle - what an extension is given to act with, and nothing more.

Success criteria

SC-001success criterion

A layer can be extended without the engine knowing it, and an extension written outside the repository composes with one written inside it.

SC-002success criterion

A mistake in a list of extensions is a value the project can show, never an exception from deep inside a layer.

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

engine/compose, engine/handle, engine/id, engine/manifest, engine/point, Data, The layers

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