IF Commons GitHub

physical/documents

Written to: 7 requirements: 7 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-estate-fleet-documents FR-001, 0005-estate-fleet-documents FR-002, 0005-estate-fleet-documents FR-003, 0005-estate-fleet-documents FR-004, 0005-estate-fleet-documents FR-005, 0005-estate-fleet-documents FR-006 and 1 more

The documents of a fleet store (commons estate 0005-estate-fleet-documents): what is kept of an estate in a store, one typed document each, with the schema that reads it and the layout that names it written as code. An asset is a document of its own and is read back through defineAsset, so a stored asset that breaks a rule of the estate is a finding and never a value. An observation is one document that is written once; a declaration and the risks accepted of an asset are one document each, changed only by a write that expects the revision it read; a reference to evidence holds the digest, never the bytes, which stay in the evidence stores of grc; and a manifest says what the store is and at which schema it is kept.

import { assetCodec, ASSETS } from "./documents.ts";
ASSETS; // "assets"
assetCodec.mediaType; // "application/json"

Source: commons/estate/src/physical/documents.ts

13 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.

FLEET_SCHEMAconst
const FLEET_SCHEMA: 1

The schema the manifest of a store says it is kept at, and the one this code reads and writes.

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

FLEET_LAYOUTconst
const FLEET_LAYOUT: 1

The layout of the folders: the paths below, as this code names them.

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

ASSETSconstno test imports it
const ASSETS: Prefix

Where the assets are: assets/<first character>/<id>.json.

OBSERVATIONSconstno test imports it
const OBSERVATIONS: Prefix

Where the observations are: observations/<asset>/<instant>.json.

DECLARATIONSconstno test imports it
const DECLARATIONS: Prefix

Where the declarations are: declarations/<first character>/<asset>.json.

ACCEPTANCESconstno test imports it
const ACCEPTANCES: Prefix

Where the accepted risks are: acceptances/<first character>/<asset>.json.

EVIDENCEconstno test imports it
const EVIDENCE: Prefix

Where the references to evidence are: evidence/<asset>/<digest>.json.

ROOT_FOLDERconstno test imports it
const ROOT_FOLDER: Prefix

The folder of the manifest, which is the root.

jsonValueconstno test imports it
const jsonValue: Decoder<Json>

A decoder of a JSON value, no deeper than 32 levels.

instantTextconstno test imports it
const instantText: Decoder<string>

A decoder of an instant: a UTC instant in the form YYYY-MM-DDTHH:MM:SS[.fff]Z that the calendar has.

instantOffunction
function instantOf(ms: number): string

The instant of a time in milliseconds, in the one form the documents use.

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

observationKeyfunction
function observationKey(at: string): Result<DocId, string>

The compact form of an instant that names an observation: the same characters with the hyphens and colons left out, so that the names sort as the instants do.

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

inputOffunction
function inputOf(asset: Asset): AssetInput

The input an asset is made from: the owners of the capabilities it offers.

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

assetCodecconst
const assetCodec: Codec<Asset>

The codec of an asset document.

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

StoredResulttypeno test imports it
type StoredResult = { readonly id: string; readonly status: "pass" | "fail" | "warn" | "unknown"; readonly controls: readonly string[] };

What a policy found, as a document keeps it.

StoredObservationtypeno test imports it
type StoredObservation = {
  readonly asset: string;
  readonly at: string;
  readonly source: string;
  readonly state: Readonly<Record<string, Json>>;
  readonly results: readonly StoredResult[];
};

An observation as it is kept: of which asset, when, attributed to which source, the keyed records seen and the results of the policies.

observationCodecconst
const observationCodec: Codec<StoredObservation>

The codec of an observation document.

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

StoredDeclarationtypeno test imports it
type StoredDeclaration = { readonly asset: string; readonly declared: Readonly<Record<string, Json>>; readonly by: string; readonly at: string };

What is declared of an asset, who declared it and when.

declarationCodecconst
const declarationCodec: Codec<StoredDeclaration>

The codec of a declaration document.

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

StoredRisktypeno test imports it
type StoredRisk = { readonly policy: string; readonly reason: string; readonly by: string; readonly until: string };

One risk a person accepted of an asset.

StoredAcceptancestypeno test imports it
type StoredAcceptances = { readonly asset: string; readonly risks: readonly StoredRisk[] };

The risks accepted of an asset, by policy.

acceptancesCodecconst
const acceptancesCodec: Codec<StoredAcceptances>

The codec of an accepted-risks document.

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

StoredEvidencetypeno test imports it
type StoredEvidence = {
  readonly subject: string;
  readonly digest: string;
  readonly store: string;
  readonly type: string;
  readonly observedAt: string;
  readonly mediaType?: string;
  readonly size?: number;
  readonly producer?: string;
};

A reference to evidence kept in an evidence store: the digest of its bytes, the store, what it is about and what kind it is. The bytes are never here.

evidenceCodecconst
const evidenceCodec: Codec<StoredEvidence>

The codec of an evidence-reference document.

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

Manifesttypeno test imports it
type Manifest = { readonly store: string; readonly schema: number; readonly layout: number; readonly created: string };

What a store says it is: which fleet, at which schema and layout it is kept, and when it was made.

manifestCodecconst
const manifestCodec: Codec<Manifest>

The codec of the manifest. It is read at any schema, so that a newer store is refused with a reason and not as an unreadable file.

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

MANIFEST_KEYconstno test imports it
const MANIFEST_KEY: DocId

The key of the manifest, fleet.json at the root.

shardedByIdconst
const shardedById: Layout<DocId>

The layout of the assets, declarations and accepted risks: one file for each asset below a folder of the first character of its identity, so that an identity of any length has a place.

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

flatByIdconst
const flatById: Layout<DocId>

The layout of the manifest and of the observations of one asset: one file for each key directly below the folder.

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

docIdOffunctionno test imports it
function docIdOf(asset: string): Result<DocId, string>

The identity of a document of an asset: the asset's identity, which is a document name.

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