IF Commons GitHub

Estate: governance

0002Active

0002-estate-governance · owner if · domain commons

Requirements

FR-001checkpassing

An asset id MUST be lower case words and digits joined by hyphens or dots, starting with a letter, at most 100 characters; an asset kind and a system id MUST be lower case words joined by hyphens; each MUST be made only by its parser and a text that is not one MUST be refused with the rule it broke.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts

Written in: estate/src/governance/ids.ts

Tests: passed: suite/governance.test.ts the identities are made only by their parsers and a text that is not one is refused with i

FR-002checkpassing

An asset MUST be discovered (seen, not adopted), adopted (someone else's install, observed and checked, never changed) or managed (changed to match what is declared: installed by the system, or taken over after it was adopted), as Stolos defines the first two (067-adopt); a discovered asset MUST offer nothing (it is listed, and nothing is scanned or recorded of it), an adopted asset MUST offer only observe and verify, and a managed asset every capability (provision, identity, plan, converge, verify, observe, update, access, backup, retire); a capability a state does not offer MUST have a reason.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts

Written in: estate/src/governance/states.ts

Tests: passed: suite/governance.test.ts each state offers what it should, a capability not offered has a reason, and an asset move

Cited by: logical/discovery, Estate: logical

FR-003checkpassing

An asset MUST move only from discovered to adopted, from adopted to discovered (released) and from adopted to managed (taken over, with an approval: 0003-estate-logical FR-003); a managed asset MUST be installed as managed or taken over, and MUST leave by being retired, and MUST NOT be moved.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts, estate/suite/logical.test.ts

Written in: estate/src/governance/states.ts

Tests: passed: suite/governance.test.ts each state offers what it should, a capability not offered has a reason, and an asset move; passed: suite/logical.test.ts an adoption and a release keep and give up owners, keep the way of joining, a managed asse

Cited by: Estate: logical

FR-004checkpassing

An asset MUST say, for every capability in the order of the closed list, that it is offered and by which system, or that it is not offered and why, so that no capability is silently dropped.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts

Written in: estate/src/governance/asset.ts

Tests: passed: suite/governance.test.ts an asset says for every capability, in order, that it is offered and by whom, or that it i

FR-005checkpassing

defineAsset MUST refuse, with every reason, an asset that names an owner for a capability its state does not offer, that leaves an offered capability with no owner, or whose identity, kind or owner is not well formed.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts

Written in: estate/src/governance/asset.ts

Tests: passed: suite/governance.test.ts an asset is refused, with every reason, for an owner of what its state does not offer, a m

FR-006checkpassing

defineEstate MUST take the assets by key (the key is the id) and the links between them, MUST make each asset by FR-005, MUST refuse a link whose end is not an asset or whose ends are the same, and the link MUST be written so that an end that is not a key of the assets does not compile.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts

Written in: estate/src/governance/estate.ts

Tests: passed: suite/governance.test.ts a typed estate makes each asset by its key, refuses a link that is wrong as data, and does

FR-007checkpassing

An asset MAY say where it came from (its origin), one of provisioned (the system installed it), paired, integration, self or scan (seen on the network and adopted); a managed asset MUST be provisioned where it says nothing, only a managed asset MUST be provisioned, and any other word MUST be refused. A managed asset that was not provisioned is inherited (someone else installed it): installOf MUST say provisioned or inherited from the origin and never store it, and an inherited asset MUST NOT offer provision (the system never reinstalls or erases what it did not install), so that naming an owner for it is refused, and its line says why.

Enforced (check): .github: cd commons/estate && bun run verify — suite/governance.test.ts

Proved by: estate/suite/governance.test.ts

Tests: passed: suite/governance.test.ts an asset says where it came from, a managed asset is provisioned by default, only a manage

Cited by: Estate: logical

Acceptance scenarios

  1. Given the text Olympia, When it is parsed as an asset id, Then it is refused naming the rule, per FR-001.
  2. Given a discovered asset, When its capabilities are read, Then none is offered and each carries the reason, per FR-002 and FR-004.
  3. Given an adopted asset that names an owner for converge, When it is defined, Then it is refused, per FR-005.
  4. Given a link to an asset that is not in the estate, When the estate is written, Then the compiler reports it, and defineEstate refuses it as data, per FR-006.
  5. Given a managed asset, When a move to adopted is asked, Then it is refused, per FR-003; and Given an adopted asset that joined as managed, When it is defined, Then it is refused, per FR-007.

Out of scope

  • What is declared of an asset: its own data, kept with it.

Edge cases

  • An asset with the same id twice cannot occur: the key of the estate is the id (FR-006).

Assumptions

  • The closed lists of states and capabilities are the ones of the library; a kind of asset is open, because a fleet names its own kinds.

Open questions

  • None.

Key entities

  • Asset - an identity, a kind, a state and a line for each capability.

Success criteria

SC-001success criterion

A reference to an asset that does not exist is a compile error in the editor.

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

logical/discovery, Estate: logical

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