FamilyVersion

KIT · interface · 类型合同

Immutable snapshot of App state at one point on a branch.

导入

TypeScript

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

JavaScript

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

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

定义

interface FamilyVersion<State>

泛型参数

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

字段结构

字段	类型	必需	说明
id	string	必需	只读。Unique version id, generated by the Kit.
parentId	string | undefined	可省略	只读。Version this one was forked or merged from, when lineage applies.
mergeSourceId	string | undefined	可省略	只读。Source version of a merge; present only on versions created by merge.
baseId	string | undefined	可省略	只读。Common ancestor recorded for fork/merge bookkeeping.
branch	AgentBranch	必需	只读。Core branch snapshot paired with this state.
state	State	必需	只读。App state; treated as immutable by the Kit and snapshotted on write.
createdAtMs	number	必需	只读。Creation instant in epoch milliseconds.

使用示例

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

相关策略源码

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

相关定义

• AgentBranch