1/**

2 * Pure types of the goal domain: the ONE home of the `goal` projection-key

3 * declaration plus the durable payload vocabulary it carries, free of this

4 * package's host-side imports (cordis events, dsh-agent, dsh-llm, the

5 * service). Two namespace projections serve it — `./types` for host

6 * consumers, `./client` (the browser half-entry's re-export) for client

7 * aggregates — with zero content duplication. Host-coupled domain

8 * vocabulary (message sources, events, fold shapes) lives in ./domain.ts.

9 *

10 * @module @deepseek-ai/dsh-goal/types

11 */

12

13import type { Branded } from '@deepseek-ai/dsh-brand'

14import type { SessionId } from '@deepseek-ai/dsh-session/types'

15

16/** Identifies one goal across its durable revisions. */

17export type GoalId = Branded<'GoalId'>

18

19/** Compare-and-set identity for one exact goal revision. */

20export interface GoalRef {

21 /** Stable goal identity. */

22 readonly id: GoalId

23 /** Positive revision; every durable mutation increments it. */

24 readonly revision: number

25}

26

27/** Input whose omitted round cap is resolved by the service configuration. */

28export interface CreateGoalRequest {

29 readonly objective: string

30 readonly maxGoalRounds?: number

31}

32

33/** Wire-safe acknowledgement of one created goal. */

34export interface CreateGoalResult {

35 readonly ref: GoalRef

36}

37

38/** Fields changed by an edit; at least one must be present. */

39export interface EditGoalRequest {

40 readonly objective?: string

41 readonly maxGoalRounds?: number

42}

43

44/** Durable continuation phase. Activation is process-local and separate. */

45export type GoalPhase =

46 | 'active'

47 | 'paused'

48 | 'blocked'

49 | 'complete'

50

51/** Machine-routable and human-readable explanation for a blocked goal. */

52export interface GoalBlockReason {

53 /** Stable lower-kebab-case classification chosen by the blocking policy. */

54 readonly code: string

55 /** Non-empty explanation shown to humans and models. */

56 readonly message: string

57}

58

59/** Full durable state written by every non-clear goal mutation. */

60export interface GoalSnapshot extends GoalRef {

61 /** Human-requested completion objective. */

62 readonly objective: string

63 /** Durable lifecycle phase. */

64 readonly phase: GoalPhase

65 /** Present exactly while `phase` is `blocked`. */

66 readonly blockedReason?: GoalBlockReason

67 /** Total admitted goal-round cap. */

68 readonly maxGoalRounds: number

69}

70

71/** Whether this live process may automatically continue an active goal. */

72export type GoalActivation = 'armed' | 'disarmed'

73

74/** Live process-local activation update forwarded to UI clients. */

75export interface GoalActivationChanged {

76 /** Session whose live goal activation changed. */

77 readonly sessionId: SessionId

78 /** Current exact activation, absent when no goal is current. */

79 readonly goal?: {

80 /** Exact current goal identity. */

81 readonly id: GoalId

82 /** Exact current goal revision. */

83 readonly revision: number

84 /** Current process-local continuation state. */

85 readonly activation: GoalActivation

86 }

87}

88

89/** Current goal projection, including values derived from the session log. */

90export interface GoalView extends GoalSnapshot {

91 /** Highest admitted round number for this goal. */

92 readonly roundsStarted: number

93 /** Epoch milliseconds of the create mutation. */

94 readonly createdAt: number

95 /** Epoch milliseconds of the latest mutation. */

96 readonly updatedAt: number

97 /** Process-local continuation eligibility; never persisted. */

98 readonly activation: GoalActivation

99}

100

101/**

102 * The `goal` projection value: the current durable goal with its replay

103 * counters, including admitted goal rounds.

104 * Activation is process-local (never persisted) and deliberately absent —

105 * the projection reflects durable phase only.

106 */

107export interface GoalProjection {

108 /** Current durable goal snapshot (the CAS ref for mutations rides on it). */

109 readonly goal: GoalSnapshot

110 /** Highest admitted round number for this goal. */

111 readonly roundsStarted: number

112 /** Epoch milliseconds of the create mutation. */

113 readonly createdAt: number

114 /** Epoch milliseconds of the latest mutation. */

115 readonly updatedAt: number

116}

117

118/** Strict checkpoint state used to derive the current goal client value. */

119export interface GoalProjectionState {

120 /** Latest valid current goal, or null before creation and after clear. */

121 readonly current: GoalProjection | null

122 /** Goal identities already created in this Session, retained to reject reuse. */

123 readonly seenGoalIds: GoalId[]

124 /** First strict replay failure, or null while the durable stream is valid. */

125 readonly failure: string | null

126}

127

128declare module '@deepseek-ai/dsh-session-projection/types' {

129 interface SessionProjectionStateMap {

130 goal: GoalProjectionState

131 }

132 interface SessionProjectionMap {

133 /**

134 * The session's current goal and admitted-round count, or

135 * `null` before the first create and after a clear tombstone.

136 * `goal/change` supplies the whole lifecycle value; matching admitted

137 * `user/message` events advance `roundsStarted`.

138 */

139 goal: GoalProjection | null

140 }

141}

142

143declare module '@deepseek-ai/cordis' {

144 interface Events {

145 /**

146 * Process-local goal activation changed for one session.

147 * @mode emit

148 * @param payload - session id and the exact current goal activation, or no goal after a clear.

149 */

150 'goal/activation-changed'(payload: GoalActivationChanged): void

151 }

152}