governance.Kindtypeno test imports ittype Kind = "report" | "action";A report only reads and says what it found; an action changes something.
What a headless action is, before any surface draws it (commons headless 0002-headless-governance): its identity, who it is for, what it may do to the world (read, mutate, destructive), whether repeating it is safe, whether it can preview itself, and which of its options only a person may give. A report only reads; an action changes something. From those facts alone decide says whether a run proceeds, previews, asks the person, or is refused, so that a command line, a tool server and a REST route decide it the same way.
This module imports Core alone and names no surface: nothing here prints, prompts or reads the environment.
import { defineAction, decide } from "./action.ts";
const wipe = defineAction({ id: "cache wipe", summary: "Delete the cache.", kind: "action", effect: "destructive", dryRun: true });
decide(wipe, { audience: "human", interactive: false, flagConfirms: true }, { mode: "apply", confirmed: false, given: [] }).kind; // "refuse"governance.Kindtypeno test imports ittype Kind = "report" | "action";A report only reads and says what it found; an action changes something.
governance.Effecttypeno test imports ittype Effect = "read" | "mutate" | "destructive";What a run may do to the world: nothing (read), something that can be undone or redone (mutate), or something that cannot be undone (destructive).
governance.Audiencetypeno test imports ittype Audience = "human" | "machine" | "both";Who an action is for: a person at a terminal, a program (a script, an agent), or both.
governance.ActionFactstypeno test imports ittype ActionFacts = {
/** Its words as a person types them (`work build`): lower-case words joined by spaces. */
read… (914 characters)type ActionFacts = {
/** Its words as a person types them (`work build`): lower-case words joined by spaces. */
readonly id: string;
readonly summary: string;
readonly kind: Kind;
readonly effect: Effect;
/** Whether running it again with the same input changes nothing more. */
readonly idempotent: boolean;
readonly audience: Audience;
/** The tier a caller must hold to see and run it (0010-audience-tiers): the lowest tier of the program's ladder unless it says otherwise. */
readonly tier: TierName;
/** Whether `--dry-run` previews what it would change and changes nothing. */
readonly dryRun: boolean;
/** Whether `--check` ends with findings where it would change something (a drift check), changing nothing. */
readonly check: boolean;
/** The options (by their keys) that only a person may give: a machine surface refuses them. */
readonly humanOnly: readonly string[];
};The facts of an action.
governance.ActionDefinitiontypeno test imports ittype ActionDefinition = {
readonly id: string;
readonly summary: string;
readonly kind: Kind;
readonly effect?: Effect;
readonly idempotent?: boolean;
readonly audience?: Audience;
readonly tier?: TierName;
readonly dryRun?: boolean;
readonly check?: boolean;
readonly humanOnly?: readonly string[];
};What defineAction takes: the identity and summary, and the facts that are not the defaults of its kind.
governance.defineActionfunctionno test imports itfunction defineAction(d: ActionDefinition): ActionFactsAn action's facts with the defaults of its kind: a report reads, is idempotent and has no preview; an action mutates, is not assumed idempotent and has no preview until it says so. Everyone is the audience unless it says otherwise.
governance.ActionRuletypeno test imports ittype ActionRule =
| "action/id"
| "action/summary"
| "action/report-changes"
| "action/action-reads"
| "action/destructive-no-preview"
| "action/idempotent-destructive"
| "action/human-only-duplicate"
| "action/check-on-read";The ways an action's facts can contradict each other.
governance.ActionProblemtypeno test imports ittype ActionProblem = { readonly rule: ActionRule; readonly message: string };A contradiction in an action's facts.
governance.actionProblemsfunctionno test imports itfunction actionProblems(a: ActionFacts): readonly ActionProblem[]Every contradiction in an action's facts, in the order of the rules.
governance.Modetypeno test imports ittype Mode = "apply" | "dry-run" | "check";How a run is to treat its effect: do it, preview it, or check for the need of it.
governance.modeOffunctionno test imports itfunction modeOf(flags: { readonly dryRun: boolean; readonly check: boolean; }): Result<Mode, string>The mode the flags ask for; both flags at once are not one mode.
governance.mayChangefunctionno test imports itfunction mayChange(mode: Mode): booleanWhether a run in this mode may change anything.
governance.SurfaceFactstypeno test imports ittype SurfaceFacts = {
/** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a … (622 characters)type SurfaceFacts = {
/** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a tool server, a REST route). */
readonly audience: "human" | "machine";
/** Whether the person can be asked a question now (a terminal on both ends). */
readonly interactive: boolean;
/** Whether `--yes` (or its like) may stand for the person's answer: a command line yes, a tool server no. */
readonly flagConfirms: boolean;
/** Whether a prior consent (`--consent <id>`) may stand for the answer; the value of `flagConfirms` where it is not said. */
readonly acceptsConsent?: boolean;
};What a surface is, for the decision: who is on the other side, whether it can ask, and whether a flag of the invocation may stand for the answer.
governance.Invocationtypeno test imports ittype Invocation = {
readonly mode: Mode;
readonly confirmed: boolean;
readonly given: readonly string[];
/** The identifier of a consent a person gave earlier, where the invocation carries one. */
readonly consent?: string;
};What the invocation gave: its mode, whether it carried the confirmation flag, and the keys of the options it set.
governance.Refusaltypeno test imports ittype Refusal = "human-only-action" | "human-only-option" | "confirmation-needed" | "confirmation-not-accepted" | "consent-needed";Why a run is refused.
governance.Decisiontypeno test imports ittype Decision =
| { readonly kind: "proceed" }
| { readonly kind: "preview" }
| { readonly kind: "ask" }
| { readonly kind: "refuse"; readonly reason: Refusal; readonly message: string };What to do with a run.
governance.humanOnlyGivenfunctionno test imports itfunction humanOnlyGiven(a: ActionFacts, given: readonly string[]): readonly string[]The options of an invocation that only a person may give.
governance.decidefunctionno test imports itfunction decide(a: ActionFacts, surface: SurfaceFacts, inv: Invocation, reach?: ReachPolicy | undefined): DecisionWhat to do with a run, from the action's facts, the surface and the invocation (FR-004, FR-005): refuse what a machine may not do, preview what is asked to be a preview, proceed with what only reads or can be undone, and for what cannot be undone ask the person, accept the flag where the surface lets a flag stand for the answer, and refuse where there is neither. Where the reach policy's confirmation class is consent, an action that changes something proceeds on a prior consent (--consent <id>), asks a person where there is one, and is refused otherwise (consent-needed).
Kindtypeno test imports ittype Kind = "report" | "action";A report only reads and says what it found; an action changes something.
Effecttypeno test imports ittype Effect = "read" | "mutate" | "destructive";What a run may do to the world: nothing (read), something that can be undone or redone (mutate), or something that cannot be undone (destructive).
Audiencetypeno test imports ittype Audience = "human" | "machine" | "both";Who an action is for: a person at a terminal, a program (a script, an agent), or both.
ActionFactstypetype ActionFacts = {
/** Its words as a person types them (`work build`): lower-case words joined by spaces. */
read… (914 characters)type ActionFacts = {
/** Its words as a person types them (`work build`): lower-case words joined by spaces. */
readonly id: string;
readonly summary: string;
readonly kind: Kind;
readonly effect: Effect;
/** Whether running it again with the same input changes nothing more. */
readonly idempotent: boolean;
readonly audience: Audience;
/** The tier a caller must hold to see and run it (0010-audience-tiers): the lowest tier of the program's ladder unless it says otherwise. */
readonly tier: TierName;
/** Whether `--dry-run` previews what it would change and changes nothing. */
readonly dryRun: boolean;
/** Whether `--check` ends with findings where it would change something (a drift check), changing nothing. */
readonly check: boolean;
/** The options (by their keys) that only a person may give: a machine surface refuses them. */
readonly humanOnly: readonly string[];
};The facts of an action.
ActionDefinitiontypeno test imports ittype ActionDefinition = {
readonly id: string;
readonly summary: string;
readonly kind: Kind;
readonly effect?: Effect;
readonly idempotent?: boolean;
readonly audience?: Audience;
readonly tier?: TierName;
readonly dryRun?: boolean;
readonly check?: boolean;
readonly humanOnly?: readonly string[];
};What defineAction takes: the identity and summary, and the facts that are not the defaults of its kind.
defineActionfunctionfunction defineAction(d: ActionDefinition): ActionFactsAn action's facts with the defaults of its kind: a report reads, is idempotent and has no preview; an action mutates, is not assumed idempotent and has no preview until it says so. Everyone is the audience unless it says otherwise.
ActionRuletypeno test imports ittype ActionRule =
| "action/id"
| "action/summary"
| "action/report-changes"
| "action/action-reads"
| "action/destructive-no-preview"
| "action/idempotent-destructive"
| "action/human-only-duplicate"
| "action/check-on-read";The ways an action's facts can contradict each other.
ActionProblemtypeno test imports ittype ActionProblem = { readonly rule: ActionRule; readonly message: string };A contradiction in an action's facts.
actionProblemsfunctionfunction actionProblems(a: ActionFacts): readonly ActionProblem[]Every contradiction in an action's facts, in the order of the rules.
Modetypetype Mode = "apply" | "dry-run" | "check";How a run is to treat its effect: do it, preview it, or check for the need of it.
modeOffunctionfunction modeOf(flags: { readonly dryRun: boolean; readonly check: boolean; }): Result<Mode, string>The mode the flags ask for; both flags at once are not one mode.
mayChangefunctionfunction mayChange(mode: Mode): booleanWhether a run in this mode may change anything.
SurfaceFactstypetype SurfaceFacts = {
/** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a … (622 characters)type SurfaceFacts = {
/** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a tool server, a REST route). */
readonly audience: "human" | "machine";
/** Whether the person can be asked a question now (a terminal on both ends). */
readonly interactive: boolean;
/** Whether `--yes` (or its like) may stand for the person's answer: a command line yes, a tool server no. */
readonly flagConfirms: boolean;
/** Whether a prior consent (`--consent <id>`) may stand for the answer; the value of `flagConfirms` where it is not said. */
readonly acceptsConsent?: boolean;
};What a surface is, for the decision: who is on the other side, whether it can ask, and whether a flag of the invocation may stand for the answer.
Invocationtypeno test imports ittype Invocation = {
readonly mode: Mode;
readonly confirmed: boolean;
readonly given: readonly string[];
/** The identifier of a consent a person gave earlier, where the invocation carries one. */
readonly consent?: string;
};What the invocation gave: its mode, whether it carried the confirmation flag, and the keys of the options it set.
Refusaltypeno test imports ittype Refusal = "human-only-action" | "human-only-option" | "confirmation-needed" | "confirmation-not-accepted" | "consent-needed";Why a run is refused.
Decisiontypetype Decision =
| { readonly kind: "proceed" }
| { readonly kind: "preview" }
| { readonly kind: "ask" }
| { readonly kind: "refuse"; readonly reason: Refusal; readonly message: string };What to do with a run.
humanOnlyGivenfunctionfunction humanOnlyGiven(a: ActionFacts, given: readonly string[]): readonly string[]The options of an invocation that only a person may give.
decidefunctionfunction decide(a: ActionFacts, surface: SurfaceFacts, inv: Invocation, reach?: ReachPolicy | undefined): DecisionWhat to do with a run, from the action's facts, the surface and the invocation (FR-004, FR-005): refuse what a machine may not do, preview what is asked to be a preview, proceed with what only reads or can be undone, and for what cannot be undone ask the person, accept the flag where the surface lets a flag stand for the answer, and refuse where there is neither. Where the reach policy's confirmation class is consent, an action that changes something proceeds on a prior consent (--consent <id>), asks a person where there is one, and is refused otherwise (consent-needed).