syncpoint-ai 0.1.0

package/dist/server/application/state-transition-service.d.ts

@@ -0,0 +1,106 @@
+/**
+ * State Transition Service — atomic state transitions with audit trail.
+ *
+ * Every state change is recorded in state_transition_log, enabling:
+ *   - Crash recovery: replay log to restore consistent state
+ *   - Debugging: trace entity lifecycle
+ *   - Audit: who changed what and when
+ *
+ * Design: Wraps SQLite transactions to ensure the transition check,
+ * state update, and log insert are atomic (all-or-nothing).
+ *
+ * DB access is delegated to state-transition-repository (Drizzle typed queries).
+ * Compensation definitions are extensible via registerCompensation().
+ */
+import { SyncPointError } from "../../kernel/index.js";
+export interface StateTransitionRecord {
+    entityType: string;
+    entityId: string;
+    fromState: string;
+    toState: string;
+    operation: string;
+    agentId: string;
+    payload?: Record<string, unknown>;
+    createdAt?: string;
+}
+/**
+ * Error thrown when a state transition fails due to state mismatch.
+ */
+export declare class StateTransitionError extends SyncPointError {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly expectedFrom: string;
+    readonly targetTo: string;
+    readonly code = "STATE_TRANSITION_ERROR";
+    readonly httpStatus = 409;
+    readonly retryable = false;
+    readonly suggestion = "Refresh the current state and retry the operation.";
+    constructor(entityType: string, entityId: string, expectedFrom: string, targetTo: string, message: string);
+    get userMessage(): string;
+}
+export interface CompensationDefinition {
+    entityType: string;
+    operation: string;
+    compensateOperation: string;
+    compensateToState: string;
+    description: string;
+}
+/**
+ * Register a compensation definition for a given entity type + operation pair.
+ * Domain modules should call this during initialization instead of editing
+ * a centralized array.
+ */
+export declare function registerCompensation(def: CompensationDefinition): void;
+/**
+ * Remove a compensation definition. Useful for testing.
+ */
+export declare function unregisterCompensation(entityType: string, operation: string): void;
+/**
+ * Clear all compensation definitions. Test utility.
+ */
+export declare function clearCompensationRegistry(): void;
+/**
+ * Execute a state transition atomically:
+ * 1. Begin transaction
+ * 2. Verify current state matches expected fromState (if validateFromState is true)
+ * 3. Execute the update callback (provided by caller)
+ * 4. Insert transition log record via repository
+ * 5. Commit
+ *
+ * If any step fails, the transaction is rolled back.
+ * Returns the transition record on success, throws on failure.
+ */
+export declare function executeAtomicTransition<T>(record: StateTransitionRecord, updateFn: () => T, options?: {
+    validateFromState?: boolean;
+}): T;
+/**
+ * Get the transition history for an entity.
+ * Delegates to repository (Drizzle typed query).
+ */
+export declare function getEntityTransitionHistory(entityType: string, entityId: string, limit?: number): StateTransitionRecord[];
+/**
+ * Find all entities currently in a non-terminal (intermediate) state.
+ * Used for crash recovery: identifies entities that might be stuck.
+ * Delegates to repository (Drizzle typed query with subquery).
+ */
+export declare function findIntermediateStateEntities(entityType: string, terminalStates: string[]): Array<{
+    entityId: string;
+    state: string;
+}>;
+/**
+ * Get the compensation definition for a given entity type and operation.
+ * Returns undefined if no compensation is defined.
+ */
+export declare function getCompensationDefinition(entityType: string, operation: string): CompensationDefinition | undefined;
+/**
+ * Get all compensation definitions, optionally filtered by entity type.
+ */
+export declare function listCompensationDefinitions(entityType?: string): CompensationDefinition[];
+/**
+ * Get the recommended recovery state for a stuck entity based on its
+ * last operation. Returns the compensation target state, or undefined
+ * if no compensation is defined (meaning the entity may be in a valid
+ * intermediate state).
+ */
+export declare function getRecoveryState(entityType: string, lastOperation: string): string | undefined;
+//# sourceMappingURL=state-transition-service.d.ts.map

package/dist/server/application/state-transition-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transition-service.d.ts","sourceRoot":"","sources":["../../../_build/src/server/application/state-transition-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAYvD,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;aAMpC,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,MAAM;aAChB,YAAY,EAAE,MAAM;aACpB,QAAQ,EAAE,MAAM;IARlC,QAAQ,CAAC,IAAI,4BAA4B;IACzC,QAAQ,CAAC,UAAU,OAAO;IAC1B,QAAQ,CAAC,SAAS,SAAS;IAC3B,QAAQ,CAAC,UAAU,wDAAwD;gBAEzD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM;IAKjB,IAAI,WAAW,IAAI,MAAM,CAExB;CACF;AA8BD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAUD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,sBAAsB,GAAG,IAAI,CAEtE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAElF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AA+FD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,EAAE,MAAM,CAAC,EACjB,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,CAAC,CAqDH;AAID;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAK,GACT,qBAAqB,EAAE,CAYzB;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EAAE,GACvB,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAE5C;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,sBAAsB,GAAG,SAAS,CAEpC;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,CAAC,EAAE,MAAM,GAClB,sBAAsB,EAAE,CAI1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAEpB"}

package/dist/server/application/state-transition-service.js

@@ -0,0 +1,291 @@
+/**
+ * State Transition Service — atomic state transitions with audit trail.
+ *
+ * Every state change is recorded in state_transition_log, enabling:
+ *   - Crash recovery: replay log to restore consistent state
+ *   - Debugging: trace entity lifecycle
+ *   - Audit: who changed what and when
+ *
+ * Design: Wraps SQLite transactions to ensure the transition check,
+ * state update, and log insert are atomic (all-or-nothing).
+ *
+ * DB access is delegated to state-transition-repository (Drizzle typed queries).
+ * Compensation definitions are extensible via registerCompensation().
+ */
+import { SyncPointError } from "../../kernel/index.js";
+import { defaultContext } from "../db.js";
+import { logger } from "../logger.js";
+import { insertTransitionLog, getEntityTransitionHistory as repoGetHistory, findIntermediateStateEntitiesFromLog, } from "../repositories/state-transition-repository.js";
+/**
+ * Error thrown when a state transition fails due to state mismatch.
+ */
+export class StateTransitionError extends SyncPointError {
+    entityType;
+    entityId;
+    expectedFrom;
+    targetTo;
+    code = "STATE_TRANSITION_ERROR";
+    httpStatus = 409;
+    retryable = false;
+    suggestion = "Refresh the current state and retry the operation.";
+    constructor(entityType, entityId, expectedFrom, targetTo, message) {
+        super(message);
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.expectedFrom = expectedFrom;
+        this.targetTo = targetTo;
+        this.name = "StateTransitionError";
+    }
+    get userMessage() {
+        return `Cannot change "${this.entityType}" "${this.entityId}" from ${this.expectedFrom} to ${this.targetTo}`;
+    }
+}
+/**
+ * Map of entity_type → table_name + status_column for state lookups.
+ * Used by getCurrentEntityState to find the current state of an entity.
+ */
+const ENTITY_STATE_TABLES = {
+    resource_claim: { table: "resource_claim", statusCol: "status" },
+    sync_gate: { table: "sync_gate", statusCol: "status" },
+    operation: { table: "operation", statusCol: "status" },
+    write_permit: { table: "write_permit", statusCol: "status" },
+    checkpoint_review: { table: "checkpoint_review", statusCol: "status" },
+    negotiation_session: { table: "negotiation_session", statusCol: "status" },
+    guard_session: { table: "guard_session", statusCol: "status" },
+};
+/**
+ * Get the current state of an entity from its database table.
+ * Returns undefined if the entity is not found or the entity type is unknown.
+ */
+function getCurrentEntityState(entityType, entityId) {
+    const mapping = ENTITY_STATE_TABLES[entityType];
+    if (!mapping)
+        return undefined;
+    const db = defaultContext.raw;
+    const row = db.prepare(`SELECT ${mapping.statusCol} as state FROM ${mapping.table} WHERE id = ?`).get(entityId);
+    return row?.state;
+}
+// ── Compensation Registry ─────────────────────────────────
+const compensationRegistry = new Map();
+function compensationKey(entityType, operation) {
+    return `${entityType}::${operation}`;
+}
+/**
+ * Register a compensation definition for a given entity type + operation pair.
+ * Domain modules should call this during initialization instead of editing
+ * a centralized array.
+ */
+export function registerCompensation(def) {
+    compensationRegistry.set(compensationKey(def.entityType, def.operation), def);
+}
+/**
+ * Remove a compensation definition. Useful for testing.
+ */
+export function unregisterCompensation(entityType, operation) {
+    compensationRegistry.delete(compensationKey(entityType, operation));
+}
+/**
+ * Clear all compensation definitions. Test utility.
+ */
+export function clearCompensationRegistry() {
+    compensationRegistry.clear();
+}
+// ── Built-in compensations (registered at module load) ───
+function registerBuiltinCompensations() {
+    // Resource Claim
+    registerCompensation({
+        entityType: "resource_claim",
+        operation: "claim",
+        compensateOperation: "release",
+        compensateToState: "released",
+        description: "If claim crashed after marking resources but before completion, release the claim",
+    });
+    registerCompensation({
+        entityType: "resource_claim",
+        operation: "extend",
+        compensateOperation: "release",
+        compensateToState: "released",
+        description: "If extend crashed, release the claim to restore consistency",
+    });
+    // Sync Gate
+    registerCompensation({
+        entityType: "sync_gate",
+        operation: "request",
+        compensateOperation: "cancel",
+        compensateToState: "cancelled",
+        description: "If gate request crashed, cancel the gate",
+    });
+    registerCompensation({
+        entityType: "sync_gate",
+        operation: "resolve",
+        compensateOperation: "reopen",
+        compensateToState: "active",
+        description: "If resolve crashed partway, reopen the gate for re-evaluation",
+    });
+    // Operation
+    registerCompensation({
+        entityType: "operation",
+        operation: "submit",
+        compensateOperation: "cancel",
+        compensateToState: "cancelled",
+        description: "If submit crashed, cancel the operation",
+    });
+    registerCompensation({
+        entityType: "operation",
+        operation: "approve",
+        compensateOperation: "reject",
+        compensateToState: "rejected",
+        description: "If approve crashed, reject the operation to prevent partial apply",
+    });
+    // Write Permit
+    registerCompensation({
+        entityType: "write_permit",
+        operation: "prepare",
+        compensateOperation: "revoke",
+        compensateToState: "revoked",
+        description: "If prepare crashed, revoke the permit",
+    });
+    // Checkpoint Review
+    registerCompensation({
+        entityType: "checkpoint_review",
+        operation: "approve",
+        compensateOperation: "cancel",
+        compensateToState: "cancelled",
+        description: "If approve crashed, cancel the review to prevent partial state",
+    });
+    registerCompensation({
+        entityType: "checkpoint_review",
+        operation: "reject",
+        compensateOperation: "cancel",
+        compensateToState: "cancelled",
+        description: "If reject crashed, cancel the review",
+    });
+    // Negotiation Session
+    registerCompensation({
+        entityType: "negotiation_session",
+        operation: "start",
+        compensateOperation: "cancel",
+        compensateToState: "cancelled",
+        description: "If session start crashed, cancel the session",
+    });
+    // Guard Session
+    registerCompensation({
+        entityType: "guard_session",
+        operation: "create",
+        compensateOperation: "revoke",
+        compensateToState: "revoked",
+        description: "If guard session creation crashed, revoke the session",
+    });
+}
+registerBuiltinCompensations();
+// ── Atomic transition ────────────────────────────────────
+/**
+ * Execute a state transition atomically:
+ * 1. Begin transaction
+ * 2. Verify current state matches expected fromState (if validateFromState is true)
+ * 3. Execute the update callback (provided by caller)
+ * 4. Insert transition log record via repository
+ * 5. Commit
+ *
+ * If any step fails, the transaction is rolled back.
+ * Returns the transition record on success, throws on failure.
+ */
+export function executeAtomicTransition(record, updateFn, options) {
+    const db = defaultContext.raw;
+    const createdAt = record.createdAt ?? new Date().toISOString();
+    const shouldValidate = options?.validateFromState ?? false;
+    const runTransition = db.transaction(() => {
+        // State guard: verify the entity is currently in the expected fromState
+        if (shouldValidate) {
+            const currentState = getCurrentEntityState(record.entityType, record.entityId);
+            if (currentState !== undefined && currentState !== record.fromState) {
+                throw new StateTransitionError(record.entityType, record.entityId, record.fromState, record.toState, `Expected current state '${record.fromState}' but found '${currentState}'`);
+            }
+        }
+        const result = updateFn();
+        insertTransitionLog({
+            entityType: record.entityType,
+            entityId: record.entityId,
+            fromState: record.fromState,
+            toState: record.toState,
+            operation: record.operation,
+            agentId: record.agentId,
+            payload: record.payload,
+            createdAt,
+        });
+        return result;
+    });
+    try {
+        const result = runTransition();
+        logger.debug("State transition committed", {
+            entityType: record.entityType,
+            entityId: record.entityId,
+            transition: `${record.fromState} → ${record.toState}`,
+            operation: record.operation,
+            agentId: record.agentId,
+        });
+        return result;
+    }
+    catch (err) {
+        logger.error("State transition failed", {
+            entityType: record.entityType,
+            entityId: record.entityId,
+            transition: `${record.fromState} → ${record.toState}`,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+// ── Query ─────────────────────────────────────────────────
+/**
+ * Get the transition history for an entity.
+ * Delegates to repository (Drizzle typed query).
+ */
+export function getEntityTransitionHistory(entityType, entityId, limit = 50) {
+    const rows = repoGetHistory(entityType, entityId, limit);
+    return rows.map(r => ({
+        entityType: r.entityType,
+        entityId: r.entityId,
+        fromState: r.fromState,
+        toState: r.toState,
+        operation: r.operation,
+        agentId: r.agentId,
+        payload: r.payload,
+        createdAt: r.createdAt,
+    }));
+}
+/**
+ * Find all entities currently in a non-terminal (intermediate) state.
+ * Used for crash recovery: identifies entities that might be stuck.
+ * Delegates to repository (Drizzle typed query with subquery).
+ */
+export function findIntermediateStateEntities(entityType, terminalStates) {
+    return findIntermediateStateEntitiesFromLog(entityType, terminalStates);
+}
+// ── Compensation Operations ──────────────────────────────
+/**
+ * Get the compensation definition for a given entity type and operation.
+ * Returns undefined if no compensation is defined.
+ */
+export function getCompensationDefinition(entityType, operation) {
+    return compensationRegistry.get(compensationKey(entityType, operation));
+}
+/**
+ * Get all compensation definitions, optionally filtered by entity type.
+ */
+export function listCompensationDefinitions(entityType) {
+    const all = Array.from(compensationRegistry.values());
+    if (!entityType)
+        return all;
+    return all.filter(d => d.entityType === entityType);
+}
+/**
+ * Get the recommended recovery state for a stuck entity based on its
+ * last operation. Returns the compensation target state, or undefined
+ * if no compensation is defined (meaning the entity may be in a valid
+ * intermediate state).
+ */
+export function getRecoveryState(entityType, lastOperation) {
+    return getCompensationDefinition(entityType, lastOperation)?.compensateToState;
+}
+//# sourceMappingURL=state-transition-service.js.map

package/dist/server/application/state-transition-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transition-service.js","sourceRoot":"","sources":["../../../_build/src/server/application/state-transition-service.ts"],"names":[],"mappings":"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"}

package/dist/server/application/sync-gate-service.d.ts

@@ -0,0 +1,125 @@
+/**
+ * SyncGate Service — synchronization barriers.
+ *
+ * Use cases:
+ *   sgRequest    — create a sync gate and move it to SYNC_REQUESTED
+ *   sgAck        — agent acknowledges a gate
+ *   sgVote       — agent votes on a gate (approve/reject/abstain/escalate)
+ *   sgReconcile  — evaluate liveness and apply state transitions
+ *   sgResolve    — manually resolve a gate (→ READY_TO_CONTINUE)
+ *   sgCancel     — cancel a gate
+ *   sgStatus     — get gate status with pending/blocked info
+ *   sgListActive — list active gates for a task/session
+ *   sgCheckAgent — check if an agent is blocked by any active gate
+ */
+import type { SyncGate, GatePolicy, GateDetailedStatus, GateAction, ResourceRef } from "../../kernel/index.js";
+export interface SyncGateRequestInput {
+    sessionId?: string;
+    taskId: string;
+    requestedByAgentId: string;
+    requiredAgentIds: string[];
+    reason?: string;
+    description?: string;
+    relatedFiles?: string[];
+    relatedResources?: ResourceRef[];
+    relatedCheckpointId?: string;
+    relatedClaimIds?: string[];
+    policy?: GatePolicy;
+}
+export interface SyncGateStatusResult {
+    gate: SyncGate;
+    pending: string[];
+    allAcknowledged: boolean;
+    isBlocking: boolean;
+}
+export interface AgentBlockCheck {
+    blocked: boolean;
+    blockingGates: SyncGate[];
+}
+/**
+ * Request a sync gate. Creates it in NEEDS_SYNC then immediately
+ * transitions to SYNC_REQUESTED.
+ */
+export declare function sgRequest(input: SyncGateRequestInput): SyncGateStatusResult;
+/**
+ * Agent acknowledges a sync gate.
+ */
+export declare function sgAck(gateId: string, agentId: string, summary?: string): SyncGateStatusResult;
+/**
+ * Cast a vote on a sync gate. Votes are separate from acks:
+ * ack = "I see it", vote = "I think we should approve/reject/escalate".
+ *
+ * Governance:
+ *   - Only required agents or escalation agents may vote.
+ *   - Vote kind must be a valid GateVoteKind.
+ *   - Duplicate votes update the agent's position (last vote wins at count time).
+ */
+export declare function sgVote(gateId: string, agentId: string, vote: string, summary?: string): SyncGateStatusResult;
+/**
+ * Evaluate gate liveness and apply resulting state transitions.
+ * Called lazily before sgCheckAgent, wakeNext, loopResume,
+ * and eagerly after sgAck, sgVote, rcRelease.
+ */
+export declare function sgReconcile(gateId: string): SyncGateStatusResult;
+/**
+ * Reconcile all active gates related to specific claim IDs.
+ * Called when claims are released to auto-resolve conflict gates.
+ *
+ * For resource_conflict gates: re-checks whether the underlying
+ * claim conflict still exists. If not, auto-resolves the gate.
+ */
+export declare function sgReconcileForClaims(claimIds: string[]): void;
+/**
+ * Resolve a sync gate (→ READY_TO_CONTINUE). Can be done from
+ * SYNC_REQUESTED or SYNC_ACKED.
+ */
+export declare function sgResolve(gateId: string, decisionSummary?: string): SyncGateStatusResult;
+/**
+ * Cancel a sync gate.
+ */
+export declare function sgCancel(gateId: string, reason?: string): SyncGate;
+/**
+ * Get detailed gate status.
+ * Performs lazy reconcile to ensure returned state reflects current liveness.
+ */
+export declare function sgStatus(gateId: string): SyncGateStatusResult;
+/**
+ * Get full detailed gate status with policy, votes, eligible voters, actions.
+ * Performs lazy reconcile first. If agentId provided, includes availableActions for that agent.
+ */
+export declare function sgStatusDetailed(gateId: string, agentId?: string): GateDetailedStatus & {
+    availableActions?: GateAction[];
+};
+/**
+ * List all sync gates with optional filters.
+ */
+export declare function sgList(opts?: {
+    taskId?: string;
+    sessionId?: string;
+    status?: string;
+}): SyncGate[];
+/**
+ * List active (blocking) sync gates.
+ * Performs lazy reconcile on all active gates first.
+ */
+export declare function sgListActive(opts?: {
+    taskId?: string;
+    sessionId?: string;
+}): SyncGate[];
+/**
+ * Batch reconcile all active gates matching the given filters.
+ * Shared entry point for sgListActive, sgCheckAgent, snapshot, and background tick.
+ */
+export declare function sgReconcileActive(opts?: {
+    taskId?: string;
+    sessionId?: string;
+}): void;
+/**
+ * Check if an agent is blocked by any active sync gate.
+ * This is the enforcement point — call before allowing resume/wake/start-work.
+ */
+export declare function sgCheckAgent(agentId: string, opts?: {
+    taskId?: string;
+    sessionId?: string;
+}): AgentBlockCheck;
+//# sourceMappingURL=sync-gate-service.d.ts.map

package/dist/server/application/sync-gate-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-gate-service.d.ts","sourceRoot":"","sources":["../../../_build/src/server/application/sync-gate-service.ts"],"names":[],"mappings":"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"}