IF Commons GitHub

governance/capture

Written to: 8 requirements: 8 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-estate-capture FR-001, 0004-estate-capture FR-002, 0004-estate-capture FR-003, 0004-estate-capture FR-004, 0004-estate-capture FR-005, 0004-estate-capture FR-006 and 2 more

How the evidence of a tenant's assets is captured, as data the compiler checks (commons estate 0004-estate-capture): which branch it is kept on, where the collector runs, how often each kind of asset is observed, whether every capture or only a change and a heartbeat is journaled and how the journal is committed, whether and when the branch is pushed, and whether a person's seal is asked for. A policy is made only by defineCapturePolicy, which fills what is left out with the defaults and refuses, with every reason, what cannot hold: a cadence longer than the freshness window allows, a heartbeat longer than the freshness of an asset it covers, a branch that is the tenant's own.

import { defineCapturePolicy } from "./capture.ts";
const p = defineCapturePolicy({ push: { mode: "after-commit" } });
p.kind === "ok" && p.value.cadence.managed; // "PT15M"

Source: commons/estate/src/governance/capture.ts

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

JournalGranularitytypeno test imports it
type JournalGranularity = "every-capture" | "changes-and-heartbeat";

Whether every capture is journaled, or only a change and a heartbeat that says the machine was looked at and had not changed.

PushModetypeno test imports it
type PushMode = "never" | "after-commit" | "every";

When the collector pushes the branch: never, after each commit, or at an interval.

SealRequirementtypeno test imports it
type SealRequirement = "never" | "on-export" | "daily";

Whether a person's seal of the journal is never asked for, asked for with an export, or due every day.

CapturePolicyInputtype
type CapturePolicyInput = { readonly branch?: string; readonly collector?: { readonly runsOn?: string }; readonly … (572 characters)
type CapturePolicyInput = {
  readonly branch?: string;
  readonly collector?: { readonly runsOn?: string };
  readonly cadence?: { readonly managed?: string; readonly adopted?: string; readonly perAsset?: Readonly<Record<string, string>> };
  readonly journal?: { readonly granularity?: JournalGranularity; readonly heartbeat?: string; readonly commit?: { readonly every?: string } };
  readonly push?: { readonly mode?: PushMode; readonly remote?: string; readonly every?: string };
  readonly sealing?: { readonly required?: SealRequirement; readonly key?: string };
};

What a policy is written with; every field is optional and a left out one has its default.

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

CapturePolicytypeno test imports it
type CapturePolicy = { readonly branch: string; readonly collector: { readonly runsOn: string }; readonly cadence:… (569 characters)
type CapturePolicy = {
  readonly branch: string;
  readonly collector: { readonly runsOn: string };
  readonly cadence: { readonly managed: string; readonly adopted: string; readonly perAsset: Readonly<Record<string, string>> };
  readonly journal: { readonly granularity: JournalGranularity; readonly heartbeat: string | null; readonly commit: { readonly every: string } };
  readonly push: { readonly mode: PushMode; readonly remote: string; readonly every: string | null };
  readonly sealing: { readonly required: SealRequirement; readonly key: string | null };
};

A capture policy: every field is there.

LONGEST_WINDOW_MSconstno test imports it
const LONGEST_WINDOW_MS: number

The longest a freshness window may be: seven days, the longest interval of continuous validation of FedRAMP 20x.

DEFAULT_CAPTURE_POLICYconst
const DEFAULT_CAPTURE_POLICY: CapturePolicy

The defaults: the controller collects, a managed asset every 15 minutes and an adopted asset every day, every capture journaled and committed hourly, nothing pushed, a seal only with an export.

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

freshnessWindowMsfunction
function freshnessWindowMs(cadenceMs: number): number

How long an observation is good for at a cadence: twice the cadence, and never more than the longest window.

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

defineCapturePolicyfunction
function defineCapturePolicy(input?: CapturePolicyInput): Result<CapturePolicy, readonly string[]>

The policy from what was written, with every reason it cannot hold where it cannot.

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

cadenceOffunction
function cadenceOf(policy: CapturePolicy, asset: { readonly id: string; readonly state: "adopted" | "discovered" | "managed"; }): string | undefined

The cadence of an asset: its own where the policy gives one, else that of its state; nothing for an asset that is not observed (a discovered asset).

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

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