governance.TierNametypeno test imports ittype TierName = Brand<string, "tier name">;The name of a tier: lower-case words joined by hyphens, made only by parseTierName.
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"governance.TierNametypeno test imports ittype TierName = Brand<string, "tier name">;The name of a tier: lower-case words joined by hyphens, made only by parseTierName.
governance.parseTierNamefunctionno test imports itfunction 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 itconst PUBLIC: TierNameThe lowest tier of the default ladder: what every caller may see.
governance.OPERATORconstno test imports itconst OPERATOR: TierNameThe middle tier of the default ladder.
governance.ADMINISTRATORconstno test imports itconst ADMINISTRATOR: TierNameThe highest tier of the default ladder.
governance.TierLaddertypeno test imports ittype 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 itconst DEFAULT_LADDER: TierLadderThe ladder of a program that declares none: public, operator, administrator; the caller who says nothing is public.
governance.LadderProblemtypeno test imports ittype 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 itfunction 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 ittype TierRefusal = "tier-too-low" | "tier-unknown";Why an action is not visible to a caller.
governance.TIER_REFUSALSconstno test imports itconst TIER_REFUSALS: readonly TierRefusal[]Every reason, for a program that walks them.
governance.TierDecisiontypeno test imports ittype 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 itfunction tierGate(ladder: TierLadder, required: TierName, held: TierName): TierDecisionThe 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 itfunction isVisible(d: TierDecision): booleanWhether the gate lets the caller see it.
governance.tierMessagefunctionno test imports itfunction 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; }): stringOne sentence for a refusal, for a surface that tells the caller why.
TierNametypetype TierName = Brand<string, "tier name">;The name of a tier: lower-case words joined by hyphens, made only by parseTierName.
parseTierNamefunctionfunction 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.
PUBLICconstconst PUBLIC: TierNameThe lowest tier of the default ladder: what every caller may see.
OPERATORconstconst OPERATOR: TierNameThe middle tier of the default ladder.
ADMINISTRATORconstconst ADMINISTRATOR: TierNameThe highest tier of the default ladder.
TierLaddertypetype 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.
DEFAULT_LADDERconstconst DEFAULT_LADDER: TierLadderThe ladder of a program that declares none: public, operator, administrator; the caller who says nothing is public.
LadderProblemtypeno test imports ittype 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.
defineLadderfunctionfunction 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.
TierRefusaltypeno test imports ittype TierRefusal = "tier-too-low" | "tier-unknown";Why an action is not visible to a caller.
TIER_REFUSALSconstno test imports itconst TIER_REFUSALS: readonly TierRefusal[]Every reason, for a program that walks them.
TierDecisiontypetype 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.
tierGatefunctionfunction tierGate(ladder: TierLadder, required: TierName, held: TierName): TierDecisionThe 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.
isVisiblefunctionfunction isVisible(d: TierDecision): booleanWhether the gate lets the caller see it.
tierMessagefunctionfunction 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; }): stringOne sentence for a refusal, for a surface that tells the caller why.