defineAgentFamily

KIT · function · 运行时值

Compile a versioned family backed by an App-owned compare-and-swap store.

Every mutation reads the record, verifies the caller's expected revision, then commits with a compare-and-swap, so concurrent writers fail with a revision conflict rather than overwriting each other. Reads are also treated as policy checks because the App binds its read rules into the store it supplies.

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core/types、@jangts/agent-core/kits、@jangts/agent-core/kits/family。

定义

泛型参数

类型参数	约束	默认类型
State	—	—
App	—	—

调用

defineAgentFamily<State, App>(definition: FamilyDefinition<State, App>): AgentFamily<State, App>

Compile a versioned family backed by an App-owned compare-and-swap store.

Every mutation reads the record, verifies the caller's expected revision, then commits with a compare-and-swap, so concurrent writers fail with a revision conflict rather than overwriting each other. Reads are also treated as policy checks because the App binds its read rules into the store it supplies.

类型参数	约束	默认类型
State	—	—
App	—	—

参数	类型	传递	说明
definition	FamilyDefinition<State, App>	必需	—

definition 的字段

字段	类型	必需	说明
store	FamilyStore<State>	必需	只读。见类型定义及调用场景。
maxVersions	number | undefined	可省略	只读。Maximum retained versions; older versions are dropped once the bound is exceeded.
retentionMs	number | undefined	可省略	只读。Retention window in milliseconds, measured from a write.
now	(() => number) | undefined	可省略	只读。Clock override for timestamps and expiry; defaults to Date.now.
isState	(value: unknown) => value is State	必需	Validates a state loaded from the store before it is used.
authorize	(operation: FamilyOperation, record: FamilyRecord<State> | undefined, context: OperationContext<App>) => MaybePromise<void>	必需	Guards one mutation; called before any write, including with an absent record.
validate	(candidate: FamilyVersion<State>, context: OperationContext<App>) => MaybePromise<void>	必需	Validates a candidate version before it is appended.
merge	((input: { base: State; target: State; source: State; }, context: OperationContext<App>) => MaybePromise<{ value?: State | undefined; conflicts: readonly string[]; }>) | undefined	可省略	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.

返回： AgentFamily<State, App>。

返回值结构

字段	类型	必需	说明
read	(id: string, context: OperationContext<App>) => Promise<FamilyRecord<State>>	必需	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>>	必需	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>>	必需	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[]; }>	必需	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>>	必需	Makes candidateId active; fails when the active version changed since expectedActiveId.

使用示例

• Agent 分支：版本、合并与显式启用：在真实 CAS 存储上管理数据分支，候选版本经检查和授权后显式启用。

配置状态检查、来源验证和三方合并

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

显式启用已批准的候选版本

扩展 · Node.js

App 在真实审批后调用；promote 仍重新执行来源、授权、版本和 CAS 检查。

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

相关策略源码

• 分支版本冲突与启用检查

相关定义

• AgentFamily
• FamilyDefinition