std/versioned

Import from @norbital-ai/std/versioned

std/versioned (§3.7, §6.3 "Versioned lineage", PH GAP-4): pure helpers over the rows of the lineage recipe (period, sealed_at, voided_at, void_reason, sealed-only noOverlap). A sealed version never changes except for a shortened period (its successor was sealed) or one void with a reason; a correction is a new draft built by cloneNext and sealed over the old version. The seal's write is held by the collection's update grant (§3.8).

Lineage type

type Lineage = {
    readonly id: string;
    readonly period: DatePeriod;
    readonly sealed_at?: Instant | string | null;
    readonly voided_at?: Instant | string | null;
    readonly void_reason?: string | null;
};

The columns of a versioned row these helpers read.

Members

Name	Type	Description
id	string
period	DatePeriod
sealed_at?	Instant | string | null
voided_at?	Instant | string | null
void_reason?	string | null

Source: packages/std/src/versioned.ts:9

cloneNext function

function cloneNext<V extends Lineage, R extends Rows = {}>(version: V, from: PlainDate | string, children?: R): Omit<V, Carried> & { period: DatePeriod; } & { [K in keyof R]: { create: Omit<R[K][number], "id" | "revision">[]; }; }

The create input of the successor draft: the version's own values (as the caller selected them) from from, open, unsealed, with each relation's rows as explicit nested creates.

Parameters

Name	Type	Description
version	V	id: string period: DatePeriod sealed_at?: Instant | string | null voided_at?: Instant | string | null void_reason?: string | null
from	PlainDate | string
children?	R

Source: packages/std/src/versioned.ts:133

onlyShortens function

function onlyShortens(before: Lineage, input: Input): string | null

For a sealed version's update: null when every change is an earlier end of its period (or a void, which voidOnce judges), else the refusal. Nested relation writes (its lines) are changes, so they are refused too.

Parameters

Name	Type	Description
before	Lineage	id: string period: DatePeriod sealed_at?: Instant | string | null voided_at?: Instant | string | null void_reason?: string | null
input	Input

Source: packages/std/src/versioned.ts:84

sealWrites function

function sealWrites<V extends Lineage>(draft: V, sealed: readonly V[], now: Instant | string): { target: V["id"]; set: { period: DatePeriod; sealed_at?: Instant | string; }; }[]

The one update list (X-24) that seals draft: the sealed version it follows ends the day before it starts, and the draft ends the day before the next sealed version, so the sealed-only noOverlap holds in the one statement.

Parameters

Name	Type	Description
draft	V	id: string period: DatePeriod sealed_at?: Instant | string | null voided_at?: Instant | string | null void_reason?: string | null
sealed	readonly V[]
now	Instant | string

Source: packages/std/src/versioned.ts:42

voidOnce function

function voidOnce(before: Lineage, input: Input): string | null

For a sealed version's update: one void, with a reason, never undone or reworded; null when admitted.

Parameters

Name	Type	Description
before	Lineage	id: string period: DatePeriod sealed_at?: Instant | string | null voided_at?: Instant | string | null void_reason?: string | null
input	Input

Source: packages/std/src/versioned.ts:107