FamilyRecord
KIT · interface · Type contract
A whole family: its versions and which version is currently active.
Import
ts
import type { FamilyRecord } from '@jangts/agent-core/kits/family';js
/** @typedef {import('@jangts/agent-core/kits/family').FamilyRecord} FamilyRecord */Other public entry points:@jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/kits, @jangts/agent-core/kits/family.
Definition
ts
interface FamilyRecord<State>Type parameters
| Type parameter | Constraint | Default type |
|---|---|---|
State | — | — |
Field structure
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Required | Read-only. Family id; also the store key. |
revision | number | Required | Read-only. Optimistic concurrency token; every accepted mutation increments it by one. |
activeId | string | Required | Read-only. Id of the active version; promotion moves this pointer. |
expiresAtMs | number | Required | Read-only. Instant after which the record is no longer retained, in epoch milliseconds. |
versions | readonly FamilyVersion<State>[] | Required | Read-only. Versions in creation order; bounded by maxVersions when configured. |
Examples
- Agent family: versions, merge, and explicit promotion: Manage data branches on real CAS storage; candidate versions are explicitly promoted after checks and authorization.
Configure state checks, source verification, and three-way merge
Configuration · Node.js
ts
import { defineAgentFamily } from '@jangts/agent-core/kits/family';
import type { FamilyStore } from '@jangts/agent-core/kits/family';
import type { OperationContext } from '@jangts/agent-core';
type State = { goal: string; sourceRevision: string };
export function family<App>(store: FamilyStore<State>,
authorize: (context: OperationContext<App>) => Promise<void>,
verify: (state: State) => Promise<void>) {
return defineAgentFamily<State, App>({
store, maxVersions: 16, retentionMs: 7 * 86400000,
isState: (value): value is State => !!value && typeof (value as State).goal === 'string'
&& typeof (value as State).sourceRevision === 'string',
authorize: (_operation, _record, context) => authorize(context),
validate: candidate => verify(candidate.state),
async merge({ base, target, source }) {
if (target.goal !== base.goal && source.goal !== base.goal && target.goal !== source.goal)
return { conflicts: ['goal'] };
return { value: target.goal === base.goal ? source : target, conflicts: [] };
},
});
}js
import { defineAgentFamily } from '@jangts/agent-core/kits/family';
export function family(store, authorize, verify) {
return defineAgentFamily({
store, maxVersions: 16, retentionMs: 7 * 86400000,
isState: (value) => !!value && typeof value.goal === 'string'
&& typeof value.sourceRevision === 'string',
authorize: (_operation, _record, context) => authorize(context),
validate: candidate => verify(candidate.state),
async merge({ base, target, source }) {
if (target.goal !== base.goal && source.goal !== base.goal && target.goal !== source.goal)
return { conflicts: ['goal'] };
return { value: target.goal === base.goal ? source : target, conflicts: [] };
},
});
}Explicitly promote an approved candidate version
Extension · Node.js
The App calls this after real approval; promote still re-runs source, authorization, revision, and CAS checks.
ts
import type { AgentFamily } from '@jangts/agent-core/kits/family';
import type { OperationContext } from '@jangts/agent-core';
export async function activate<State, App>(family: AgentFamily<State, App>, id: string,
candidateId: string, context: OperationContext<App>) {
const record = await family.read(id, context);
return family.promote({ id, revision: record.revision, candidateId,
expectedActiveId: record.activeId }, context);
}js
export async function activate(family, id, candidateId, context) {
const record = await family.read(id, context);
return family.promote({ id, revision: record.revision, candidateId,
expectedActiveId: record.activeId }, context);
}