IF Commons GitHub

governance/tier

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0010-audience-tiers FR-001, 0010-audience-tiers FR-002, 0010-audience-tiers FR-003, 0010-audience-tiers FR-004

The tier of an action, as governance (commons headless 0010-audience-tiers): who among the callers of a program may see and run it. A tier is a name on a ladder that the program declares as data (lowest first), an action declares the tier it needs, a caller holds one, and tierGate is the one pure function that says whether the caller may see the action. Every surface asks it, so a command line, a tool server and a REST route expose the same verbs to the same caller.

A tier is not the action's audience (who the action is for: a person, a program or both) and not its effect: the audience says what kind of caller, the tier says how much that caller is trusted with; a surface applies both. A name that is not on the ladder is never visible: a typo in an action's tier hides the action, it does not expose it. The names are made only by parseTierName (parse, don't validate), and a ladder only by defineLadder.

import { DEFAULT_LADDER, OPERATOR, tierGate } from "./tier.ts";
tierGate(DEFAULT_LADDER, OPERATOR, DEFAULT_LADDER.default).kind; // "hidden"

Source: commons/headless/src/governance/tier.ts

12 of 30 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

governance.TierNametypeno test imports it
type TierName = Brand<string, "tier name">;

The name of a tier: lower-case words joined by hyphens, made only by parseTierName.

governance.parseTierNamefunctionno test imports it
function parseTierName(text: string): Result<TierName, string>

A tier name from text, or why the text is not one: the one way a TierName is made.

governance.PUBLICconstno test imports it
const PUBLIC: TierName

The lowest tier of the default ladder: what every caller may see.

governance.OPERATORconstno test imports it
const OPERATOR: TierName

The middle tier of the default ladder.

governance.ADMINISTRATORconstno test imports it
const ADMINISTRATOR: TierName

The highest tier of the default ladder.

governance.TierLaddertypeno test imports it
type TierLadder = {
  readonly ladder: readonly TierName[];
  /** The tier held by a caller whose surface does not say; one of `ladder`. */
  readonly default: TierName;
};

The tiers a program declares, lowest first, and the tier of a caller who says nothing. Data: a program may declare its own.

governance.DEFAULT_LADDERconstno test imports it
const DEFAULT_LADDER: TierLadder

The ladder of a program that declares none: public, operator, administrator; the caller who says nothing is public.

governance.LadderProblemtypeno test imports it
type LadderProblem =
  | { readonly rule: "tier/name"; readonly name: string; readonly message: string }
  | { readonly rule: "tier/empty" }
  | { readonly rule: "tier/duplicate"; readonly name: string }
  | { readonly rule: "tier/default-unknown"; readonly name: string };

What is wrong with a ladder.

governance.defineLadderfunctionno test imports it
function defineLadder(names: readonly string[], defaultName?: string | undefined): Result<TierLadder, readonly LadderProblem[]>

A ladder from names, lowest first, and the default (the lowest where none is given), or everything wrong with it.

governance.TierRefusaltypeno test imports it
type TierRefusal = "tier-too-low" | "tier-unknown";

Why an action is not visible to a caller.

governance.TIER_REFUSALSconstno test imports it
const TIER_REFUSALS: readonly TierRefusal[]

Every reason, for a program that walks them.

governance.TierDecisiontypeno test imports it
type TierDecision =
  | { readonly kind: "visible" }
  | { readonly kind: "hidden"; readonly reason: "tier-too-low"; readonly required: TierName; readonly held: TierName }
  | { readonly kind: "hidden"; readonly reason: "tier-unknown"; readonly unknown: TierName; readonly required: TierName; readonly held: TierName };

Whether an action is visible to a caller of a tier, and where it is not, why.

governance.tierGatefunctionno test imports it
function tierGate(ladder: TierLadder, required: TierName, held: TierName): TierDecision

The gate: whether a caller who holds held may see an action that needs required, on a ladder. A caller sees an action whose tier is at or below its own; a tier that is not on the ladder (the action's or the caller's) hides the action, and says which. Pure: the same three values always give the same answer.

governance.isVisiblefunctionno test imports it
function isVisible(d: TierDecision): boolean

Whether the gate lets the caller see it.

governance.tierMessagefunctionno test imports it
function tierMessage(actionId: string, d: { readonly kind: "hidden"; readonly reason: "tier-too-low"; readonly required: TierName; readonly held: TierName; } | { readonly kind: "hidden"; readonly reason: "tier-unknown"; readonly unknown: TierName; readonly required: TierName; readonly held: TierName; }): string

One sentence for a refusal, for a surface that tells the caller why.

TierNametype
type TierName = Brand<string, "tier name">;

The name of a tier: lower-case words joined by hyphens, made only by parseTierName.

Imported by 22 tests of the run (22 passed, 0 failed): the library's results

parseTierNamefunction
function parseTierName(text: string): Result<TierName, string>

A tier name from text, or why the text is not one: the one way a TierName is made.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

PUBLICconst
const PUBLIC: TierName

The lowest tier of the default ladder: what every caller may see.

Imported by 30 tests of the run (30 passed, 0 failed): the library's results

OPERATORconst
const OPERATOR: TierName

The middle tier of the default ladder.

Imported by 28 tests of the run (28 passed, 0 failed): the library's results

ADMINISTRATORconst
const ADMINISTRATOR: TierName

The highest tier of the default ladder.

Imported by 22 tests of the run (22 passed, 0 failed): the library's results

TierLaddertype
type TierLadder = {
  readonly ladder: readonly TierName[];
  /** The tier held by a caller whose surface does not say; one of `ladder`. */
  readonly default: TierName;
};

The tiers a program declares, lowest first, and the tier of a caller who says nothing. Data: a program may declare its own.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

DEFAULT_LADDERconst
const DEFAULT_LADDER: TierLadder

The ladder of a program that declares none: public, operator, administrator; the caller who says nothing is public.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

LadderProblemtypeno test imports it
type LadderProblem =
  | { readonly rule: "tier/name"; readonly name: string; readonly message: string }
  | { readonly rule: "tier/empty" }
  | { readonly rule: "tier/duplicate"; readonly name: string }
  | { readonly rule: "tier/default-unknown"; readonly name: string };

What is wrong with a ladder.

defineLadderfunction
function defineLadder(names: readonly string[], defaultName?: string | undefined): Result<TierLadder, readonly LadderProblem[]>

A ladder from names, lowest first, and the default (the lowest where none is given), or everything wrong with it.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

TierRefusaltypeno test imports it
type TierRefusal = "tier-too-low" | "tier-unknown";

Why an action is not visible to a caller.

TIER_REFUSALSconstno test imports it
const TIER_REFUSALS: readonly TierRefusal[]

Every reason, for a program that walks them.

TierDecisiontype
type TierDecision =
  | { readonly kind: "visible" }
  | { readonly kind: "hidden"; readonly reason: "tier-too-low"; readonly required: TierName; readonly held: TierName }
  | { readonly kind: "hidden"; readonly reason: "tier-unknown"; readonly unknown: TierName; readonly required: TierName; readonly held: TierName };

Whether an action is visible to a caller of a tier, and where it is not, why.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

tierGatefunction
function tierGate(ladder: TierLadder, required: TierName, held: TierName): TierDecision

The gate: whether a caller who holds held may see an action that needs required, on a ladder. A caller sees an action whose tier is at or below its own; a tier that is not on the ladder (the action's or the caller's) hides the action, and says which. Pure: the same three values always give the same answer.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

isVisiblefunction
function isVisible(d: TierDecision): boolean

Whether the gate lets the caller see it.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

tierMessagefunction
function tierMessage(actionId: string, d: { readonly kind: "hidden"; readonly reason: "tier-too-low"; readonly required: TierName; readonly held: TierName; } | { readonly kind: "hidden"; readonly reason: "tier-unknown"; readonly unknown: TierName; readonly required: TierName; readonly held: TierName; }): string

One sentence for a refusal, for a surface that tells the caller why.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

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