FamilyDefinition

KIT · interface · Type contract

App-owned hooks and limits for one family.

Import

TypeScript

import type { FamilyDefinition } from '@jangts/agent-core/kits/family';

JavaScript

/** @typedef {import('@jangts/agent-core/kits/family').FamilyDefinition} FamilyDefinition */

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/kits, @jangts/agent-core/kits/family.

Definition

interface FamilyDefinition<State, App>

Type parameters

Type parameter	Constraint	Default type
State	—	—
App	—	—

Field structure

Field	Type	Required	Description
store	FamilyStore<State>	Required	Read-only. See the type definition and usage context.
maxVersions	number | undefined	Optional	Read-only. Maximum retained versions; older versions are dropped once the bound is exceeded.
retentionMs	number | undefined	Optional	Read-only. Retention window in milliseconds, measured from a write.
now	(() => number) | undefined	Optional	Read-only. Clock override for timestamps and expiry; defaults to Date.now.
isState	(value: unknown) => value is State	Required	Validates a state loaded from the store before it is used.
authorize	(operation: FamilyOperation, record: FamilyRecord<State> | undefined, context: OperationContext<App>) => MaybePromise<void>	Required	Guards one mutation; called before any write, including with an absent record.
validate	(candidate: FamilyVersion<State>, context: OperationContext<App>) => MaybePromise<void>	Required	Validates a candidate version before it is appended.
merge	((input: { base: State; target: State; source: State; }, context: OperationContext<App>) => MaybePromise<{ value?: State; conflicts: readonly string[]; }>) | undefined	Optional	Resolves a three-way merge. Returns the merged state and any conflicts. A non-empty conflict list aborts the merge without writing a version, so value is ignored in that case.

Member index

Member	Purpose
isState	Validates a state loaded from the store before it is used.
authorize	Guards one mutation; called before any write, including with an absent record.
validate	Validates a candidate version before it is appended.

Member details

isState

Validates a state loaded from the store before it is used.

FamilyDefinition.isState(value: unknown): value is State

Validates a state loaded from the store before it is used.

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: boolean.

authorize

Guards one mutation; called before any write, including with an absent record.

FamilyDefinition.authorize(operation: FamilyOperation, record: FamilyRecord<State> | undefined, context: OperationContext<App>): MaybePromise<void>

Guards one mutation; called before any write, including with an absent record.

Parameter	Type	Passing	Description
operation	"create" | "fork" | "merge" | "promote"	Required	—
record	FamilyRecord<State> | undefined	Required	—
context	OperationContext<App>	Required	—

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Optional shapes of Parameter record: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

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.

Returns: MaybePromise<void>.

Awaited value: void.

validate

Validates a candidate version before it is appended.

FamilyDefinition.validate(candidate: FamilyVersion<State>, context: OperationContext<App>): MaybePromise<void>

Validates a candidate version before it is appended.

Parameter	Type	Passing	Description
candidate	FamilyVersion<State>	Required	—
context	OperationContext<App>	Required	—

Fields of candidate

Field	Type	Required	Description
id	string	Required	Read-only. Unique version id, generated by the Kit.
parentId	string | undefined	Optional	Read-only. Version this one was forked or merged from, when lineage applies.
mergeSourceId	string | undefined	Optional	Read-only. Source version of a merge; present only on versions created by merge.
baseId	string | undefined	Optional	Read-only. Common ancestor recorded for fork/merge bookkeeping.
branch	AgentBranch	Required	Read-only. Core branch snapshot paired with this state.
state	State	Required	Read-only. App state; treated as immutable by the Kit and snapshotted on write.
createdAtMs	number	Required	Read-only. Creation instant in epoch milliseconds.

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: MaybePromise<void>.

Awaited value: void.

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

TypeScript

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: [] };
    },
  });
}

JavaScript

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.

TypeScript

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);
}

JavaScript

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);
}

Related policy source

• Branch version conflicts and promotion checks

Related definitions

• FamilyOperation
• FamilyRecord
• FamilyStore
• FamilyVersion
• MaybePromise
• OperationContext