IF Commons GitHub

governance/fidelity

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-anyfs-posix-governance FR-002, 0002-anyfs-posix-governance FR-003

How faithfully an operation is carried out, as a closed union: native where the store does what POSIX says, emulated where the library does it with other operations (and says what that costs), and refused where the store has no way to do it. Nothing is pretended: every result of the library carries one, an emulation names its reason and the risk it brings, and a program that will not take a risk reads it from the label and stops.

import { emulated, isStrictViolation, native } from "./fidelity.ts";
isStrictViolation(native); // false
isStrictViolation(emulated("copy-then-delete")); // true: a copy and a delete are not one change

Source: commons/anyfs-posix/src/governance/fidelity.ts

11 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.RISKSconstno test imports it
const RISKS: readonly ["none", "cost", "deferred", "lossy", "non-atomic", "unguarded", "not-durable"]

What an emulation risks, from the least to the most: nothing, cost (more calls or bytes), a result that is not there until close, a detail that is not kept, a change that is not one, a write that is not guarded, a change that does not persist.

governance.Risktypeno test imports it
type Risk = (typeof RISKS)[number];

One risk.

governance.STRICT_RISKSconstno test imports it
const STRICT_RISKS: readonly ("cost" | "deferred" | "lossy" | "non-atomic" | "none" | "not-durable" | "unguarded")[]

The risks a program that asks for strictness will not take: the ones that lose or change something it did not mean to.

governance.EMULATIONSconstno test imports it
const EMULATIONS: readonly ["derived-directory", "marker-object", "no-marker", "write-back-buffer", "unguarded-write", "whole-object-range", "read-modify-write", "copy-then-delete", "listing-walk", "touch-without-mtime"]

How the library does what a store cannot: a closed list.

governance.EmulationReasontypeno test imports it
type EmulationReason = (typeof EMULATIONS)[number];

One way of emulating.

governance.EMULATION_FACTSconstno test imports it
const EMULATION_FACTS: Readonly<Record<"copy-then-delete" | "derived-directory" | "listing-walk" | "marker-object" | "no-marker" | "read-modify-write" | "touch-without-mtime" | "unguarded-write" | "whole-object-range" | "write-back-buffer", { readonly risk: "cost" | "deferred" | "lossy" | "non-atomic" | "none" | "not-durable" | "unguarded"; readonly summary: string; }>>

What each emulation risks, and says.

governance.REFUSALS_OF_POSIXconstno test imports it
const REFUSALS_OF_POSIX: readonly ["not-in-model", "capability-absent", "read-only"]

Why the library does not do it: a closed list.

governance.PosixRefusaltypeno test imports it
type PosixRefusal = (typeof REFUSALS_OF_POSIX)[number];

One reason for a refusal.

governance.Fidelitytypeno test imports it
type Fidelity =
  | { readonly kind: "native" }
  | { readonly kind: "emulated"; readonly reason: EmulationReason; readonly risk: Risk; readonly detail: string }
  | { readonly kind: "refused"; readonly reason: PosixRefusal; readonly detail: string };

How an operation is carried out.

governance.nativeconstno test imports it
const native: Fidelity

The store does what POSIX says.

governance.emulatedfunctionno test imports it
function emulated(reason: "copy-then-delete" | "derived-directory" | "listing-walk" | "marker-object" | "no-marker" | "read-modify-write" | "touch-without-mtime" | "unguarded-write" | "whole-object-range" | "write-back-buffer", detail?: string | undefined): Fidelity

The library does it with other operations: the risk and the sentence are the reason's, unless a sentence of this case is given.

governance.refusedByfunctionno test imports it
function refusedBy(reason: "capability-absent" | "not-in-model" | "read-only", detail: string): Fidelity

The library will not do it, and says why.

governance.describeFidelityfunctionno test imports it
function describeFidelity(fidelity: Fidelity): string

A fidelity in one line.

governance.isStrictViolationfunctionno test imports it
function isStrictViolation(fidelity: Fidelity): boolean

Whether a program that asks for strictness stops at this: an emulation with a risk that loses or changes something it did not mean to, or a refusal.

governance.worsefunctionno test imports it
function worse(a: Fidelity, b: Fidelity): Fidelity

The worse of two fidelities: a refusal is worse than an emulation, an emulation of more risk is worse than one of less, and an emulation is worse than native.

RISKSconst
const RISKS: readonly ["none", "cost", "deferred", "lossy", "non-atomic", "unguarded", "not-durable"]

What an emulation risks, from the least to the most: nothing, cost (more calls or bytes), a result that is not there until close, a detail that is not kept, a change that is not one, a write that is not guarded, a change that does not persist.

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

Risktypeno test imports it
type Risk = (typeof RISKS)[number];

One risk.

STRICT_RISKSconst
const STRICT_RISKS: readonly ("cost" | "deferred" | "lossy" | "non-atomic" | "none" | "not-durable" | "unguarded")[]

The risks a program that asks for strictness will not take: the ones that lose or change something it did not mean to.

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

EMULATIONSconst
const EMULATIONS: readonly ["derived-directory", "marker-object", "no-marker", "write-back-buffer", "unguarded-write", "whole-object-range", "read-modify-write", "copy-then-delete", "listing-walk", "touch-without-mtime"]

How the library does what a store cannot: a closed list.

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

EmulationReasontypeno test imports it
type EmulationReason = (typeof EMULATIONS)[number];

One way of emulating.

EMULATION_FACTSconst
const EMULATION_FACTS: Readonly<Record<"copy-then-delete" | "derived-directory" | "listing-walk" | "marker-object" | "no-marker" | "read-modify-write" | "touch-without-mtime" | "unguarded-write" | "whole-object-range" | "write-back-buffer", { readonly risk: "cost" | "deferred" | "lossy" | "non-atomic" | "none" | "not-durable" | "unguarded"; readonly summary: string; }>>

What each emulation risks, and says.

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

REFUSALS_OF_POSIXconst
const REFUSALS_OF_POSIX: readonly ["not-in-model", "capability-absent", "read-only"]

Why the library does not do it: a closed list.

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

PosixRefusaltypeno test imports it
type PosixRefusal = (typeof REFUSALS_OF_POSIX)[number];

One reason for a refusal.

Fidelitytypeno test imports it
type Fidelity =
  | { readonly kind: "native" }
  | { readonly kind: "emulated"; readonly reason: EmulationReason; readonly risk: Risk; readonly detail: string }
  | { readonly kind: "refused"; readonly reason: PosixRefusal; readonly detail: string };

How an operation is carried out.

nativeconst
const native: Fidelity

The store does what POSIX says.

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

emulatedfunction
function emulated(reason: "copy-then-delete" | "derived-directory" | "listing-walk" | "marker-object" | "no-marker" | "read-modify-write" | "touch-without-mtime" | "unguarded-write" | "whole-object-range" | "write-back-buffer", detail?: string | undefined): Fidelity

The library does it with other operations: the risk and the sentence are the reason's, unless a sentence of this case is given.

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

refusedByfunction
function refusedBy(reason: "capability-absent" | "not-in-model" | "read-only", detail: string): Fidelity

The library will not do it, and says why.

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

describeFidelityfunction
function describeFidelity(fidelity: Fidelity): string

A fidelity in one line.

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

isStrictViolationfunction
function isStrictViolation(fidelity: Fidelity): boolean

Whether a program that asks for strictness stops at this: an emulation with a risk that loses or changes something it did not mean to, or a refusal.

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

worsefunction
function worse(a: Fidelity, b: Fidelity): Fidelity

The worse of two fidelities: a refusal is worse than an emulation, an emulation of more risk is worse than one of less, and an emulation is worse than native.

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

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