trellis/dist/vcs/branch.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Branch Management Module
 *
 * Extracted from engine.ts per DESIGN.md §8.1.
 * Handles create, switch, list, delete branch operations.
 */
import { writerPrincipal, branchHeadEntity } from './types.js';
import type { VcsOp } from './types.js';
import type { EngineContext } from './engine-context.js';
export interface BranchInfo {
    name: string;
    isCurrent: boolean;
    createdAt?: string;
}
export interface BranchState {
    currentBranch: string;
    /** Active agent lane (W1.1). */
    activeLaneId?: string;
}
/** Whether an integration-journal op should emit a follow-up branchAdvance (ADR 0004). */
export declare function shouldAdvanceBranchHead(kind: string): boolean;
/**
 * Read branch:NAME headOpHash.
 *
 * Resolved from the causally-ordered op log, NOT the materialized fact-set. The
 * `headOpHash` facts are accumulated add-only (ADR 0022 §1) so their store
 * insertion order is network-arrival order — two peers with identical ops would
 * otherwise resolve different heads. The ops themselves are hash-chained and
 * timestamp-ordered, so the last `branchAdvance` for the branch is deterministic
 * across peers.
 *
 * `principal` scopes the head to one writer's per-principal ref zone (ADR 0022 §4):
 * two writers advancing the *same* personal branch never share a pointer, so the
 * order-dependence dissolves instead of needing a convergence rule. When omitted,
 * the head is the integration-style single-owner ref — the one audit trail where
 * position-order is meaningful because a single principal advances it. The writer
 * key is the signed `did:key` principal (`vcs.signedBy`), falling back to the
 * self-asserted `agentId` for unsigned ops.
 */
export declare function getBranchHeadOpHash(ctx: EngineContext, branchName: string, principal?: string): string | undefined;
export { writerPrincipal, branchHeadEntity };
/**
 * Create a new branch forked from the current branch.
 */
export declare function createBranch(ctx: EngineContext, name: string, currentBranch: string): Promise<VcsOp>;
/**
 * Switch to an existing branch.
 */
export declare function switchBranch(ctx: EngineContext, name: string): void;
/**
 * List all branches.
 */
export declare function listBranches(ctx: EngineContext, currentBranch: string): BranchInfo[];
/**
 * Delete a branch (cannot delete the current branch).
 */
export declare function deleteBranch(ctx: EngineContext, name: string, currentBranch: string): Promise<VcsOp>;
export declare function saveBranchState(rootPath: string, state: BranchState): void;
export declare function loadBranchState(rootPath: string): BranchState;
//# sourceMappingURL=branch.d.ts.map