FamilyDefinition

KIT · interface · 类型合同

App-owned hooks and limits for one family.

导入

TypeScript

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

JavaScript

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

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

定义

interface FamilyDefinition<State, App>

泛型参数

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

字段结构

字段	类型	必需	说明
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; 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.

成员目录

成员	用途
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.

成员详情

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.

参数	类型	传递	说明
value	unknown	必需	—

返回： 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.

参数	类型	传递	说明
operation	"create" | "fork" | "merge" | "promote"	必需	—
record	FamilyRecord<State> | undefined	必需	—
context	OperationContext<App>	必需	—

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

参数 record的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string	必需	只读。Family id; also the store key.
revision	number	必需	只读。Optimistic concurrency token; every accepted mutation increments it by one.
activeId	string	必需	只读。Id of the active version; promotion moves this pointer.
expiresAtMs	number	必需	只读。Instant after which the record is no longer retained, in epoch milliseconds.
versions	readonly FamilyVersion<State>[]	必需	只读。Versions in creation order; bounded by maxVersions when configured.

返回： MaybePromise<void>。

等待后的值： 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.

参数	类型	传递	说明
candidate	FamilyVersion<State>	必需	—
context	OperationContext<App>	必需	—

candidate 的字段

字段	类型	必需	说明
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.

context 的字段

字段	类型	必需	说明
app	unknown extends App ? App : Readonly<App>	必需	只读。见类型定义及调用场景。
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： MaybePromise<void>。

等待后的值： void。

使用示例

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

相关策略源码

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

相关定义

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