AgentFamily

KIT · interface · Type contract

Compiled family API. Every mutation returns the record after the write.

Import

TypeScript

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

JavaScript

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

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

Definition

interface AgentFamily<State, App>

Type parameters

Type parameter	Constraint	Default type
State	—	—
App	—	—

Field structure

Field	Type	Required	Description
read	(id: string, context: OperationContext<App>) => Promise<FamilyRecord<State>>	Required	Reads the record; throws when the family does not exist or has expired.
create	(request: { id: string; branch: AgentBranch; state: State; }, context: OperationContext<App>) => Promise<FamilyRecord<State>>	Required	Creates the first version and makes it active.
fork	(request: { id: string; revision: number; parentId: string; branch: AgentBranch; state: State; }, context: OperationContext<App>) => Promise<FamilyRecord<State>>	Required	Appends a version forked from parentId; the active pointer does not change.
merge	(request: { id: string; revision: number; baseId: string; targetId: string; sourceId: string; }, context: OperationContext<App>) => Promise<{ saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }>	Required	Merges source into target; saved is false when the merge reported conflicts.
promote	(request: { id: string; revision: number; candidateId: string; expectedActiveId: string; }, context: OperationContext<App>) => Promise<FamilyRecord<State>>	Required	Makes candidateId active; fails when the active version changed since expectedActiveId.

Member index

Member	Purpose
read	Reads the record; throws when the family does not exist or has expired.
create	Creates the first version and makes it active.
fork	Appends a version forked from parentId; the active pointer does not change.
merge	Merges source into target; saved is false when the merge reported conflicts.
promote	Makes candidateId active; fails when the active version changed since expectedActiveId.

Member details

read

Reads the record; throws when the family does not exist or has expired.

AgentFamily.read(id: string, context: OperationContext<App>): Promise<FamilyRecord<State>>

Reads the record; throws when the family does not exist or has expired.

Parameter	Type	Passing	Description
id	string	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.

Returns: Promise<FamilyRecord<State>>.

Awaited value: FamilyRecord<State>.

Return value 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.

create

Creates the first version and makes it active.

AgentFamily.create(request: { id: string; branch: AgentBranch; state: State; }, context: OperationContext<App>): Promise<FamilyRecord<State>>

Creates the first version and makes it active.

Parameter	Type	Passing	Description
request	{ id: string; branch: AgentBranch; state: State; }	Required	—
context	OperationContext<App>	Required	—

Fields of request

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
branch	AgentBranch	Required	See the type definition and usage context.
state	State	Required	See the type definition and usage context.

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: Promise<FamilyRecord<State>>.

Awaited value: FamilyRecord<State>.

Return value 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.

fork

Appends a version forked from parentId; the active pointer does not change.

AgentFamily.fork(request: { id: string; revision: number; parentId: string; branch: AgentBranch; state: State; }, context: OperationContext<App>): Promise<FamilyRecord<State>>

Appends a version forked from parentId; the active pointer does not change.

Parameter	Type	Passing	Description
request	{ id: string; revision: number; parentId: string; branch: AgentBranch; state: State; }	Required	—
context	OperationContext<App>	Required	—

Fields of request

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
revision	number	Required	See the type definition and usage context.
parentId	string	Required	See the type definition and usage context.
branch	AgentBranch	Required	See the type definition and usage context.
state	State	Required	See the type definition and usage context.

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: Promise<FamilyRecord<State>>.

Awaited value: FamilyRecord<State>.

Return value 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.

merge

Merges source into target; saved is false when the merge reported conflicts.

AgentFamily.merge(request: { id: string; revision: number; baseId: string; targetId: string; sourceId: string; }, context: OperationContext<App>): Promise<{ saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }>

Merges source into target; saved is false when the merge reported conflicts.

Parameter	Type	Passing	Description
request	{ id: string; revision: number; baseId: string; targetId: string; sourceId: string; }	Required	—
context	OperationContext<App>	Required	—

Fields of request

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
revision	number	Required	See the type definition and usage context.
baseId	string	Required	See the type definition and usage context.
targetId	string	Required	See the type definition and usage context.
sourceId	string	Required	See the type definition and usage context.

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: Promise<{ saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }>.

Awaited value: { saved: boolean; record: FamilyRecord<State>; conflicts: readonly string[]; }.

Return value structure

Field	Type	Required	Description
saved	boolean	Required	See the type definition and usage context.
record	FamilyRecord<State>	Required	See the type definition and usage context.
conflicts	readonly string[]	Required	See the type definition and usage context.

promote

Makes candidateId active; fails when the active version changed since expectedActiveId.

AgentFamily.promote(request: { id: string; revision: number; candidateId: string; expectedActiveId: string; }, context: OperationContext<App>): Promise<FamilyRecord<State>>

Makes candidateId active; fails when the active version changed since expectedActiveId.

Parameter	Type	Passing	Description
request	{ id: string; revision: number; candidateId: string; expectedActiveId: string; }	Required	—
context	OperationContext<App>	Required	—

Fields of request

Field	Type	Required	Description
id	string	Required	See the type definition and usage context.
revision	number	Required	See the type definition and usage context.
candidateId	string	Required	See the type definition and usage context.
expectedActiveId	string	Required	See the type definition and usage context.

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: Promise<FamilyRecord<State>>.

Awaited value: FamilyRecord<State>.

Return value 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

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

• AgentBranch
• FamilyRecord
• OperationContext