@deepseek-ai/dsh-goal 0.0.1-rc.1

package/src/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure types of the goal domain: the ONE home of the `goal` projection-key
+ * declaration plus the durable payload vocabulary it carries, free of this
+ * package's host-side imports (cordis events, dsh-agent, dsh-llm, the
+ * service). Two namespace projections serve it — `./types` for host
+ * consumers, `./client` (the browser half-entry's re-export) for client
+ * aggregates — with zero content duplication. Host-coupled domain
+ * vocabulary (message sources, events, fold shapes) lives in ./domain.ts.
+ *
+ * @module @deepseek-ai/dsh-goal/types
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Identifies one goal across its durable revisions. */
+export type GoalId = Branded<'GoalId'>
+
+/** Compare-and-set identity for one exact goal revision. */
+export interface GoalRef {
+  /** Stable goal identity. */
+  readonly id: GoalId
+  /** Positive revision; every durable mutation increments it. */
+  readonly revision: number
+}
+
+/** Input whose omitted round cap is resolved by the service configuration. */
+export interface CreateGoalRequest {
+  readonly objective: string
+  readonly maxGoalRounds?: number
+}
+
+/** Wire-safe acknowledgement of one created goal. */
+export interface CreateGoalResult {
+  readonly ref: GoalRef
+}
+
+/** Fields changed by an edit; at least one must be present. */
+export interface EditGoalRequest {
+  readonly objective?: string
+  readonly maxGoalRounds?: number
+}
+
+/** Durable continuation phase. Activation is process-local and separate. */
+export type GoalPhase =
+  | 'active'
+  | 'paused'
+  | 'blocked'
+  | 'complete'
+
+/** Machine-routable and human-readable explanation for a blocked goal. */
+export interface GoalBlockReason {
+  /** Stable lower-kebab-case classification chosen by the blocking policy. */
+  readonly code: string
+  /** Non-empty explanation shown to humans and models. */
+  readonly message: string
+}
+
+/** Full durable state written by every non-clear goal mutation. */
+export interface GoalSnapshot extends GoalRef {
+  /** Human-requested completion objective. */
+  readonly objective: string
+  /** Durable lifecycle phase. */
+  readonly phase: GoalPhase
+  /** Present exactly while `phase` is `blocked`. */
+  readonly blockedReason?: GoalBlockReason
+  /** Total admitted goal-round cap. */
+  readonly maxGoalRounds: number
+}
+
+/** Whether this live process may automatically continue an active goal. */
+export type GoalActivation = 'armed' | 'disarmed'
+
+/** Current goal projection, including values derived from the session log. */
+export interface GoalView extends GoalSnapshot {
+  /** Highest admitted round number for this goal. */
+  readonly roundsStarted: number
+  /** Epoch milliseconds of the create mutation. */
+  readonly createdAt: number
+  /** Epoch milliseconds of the latest mutation. */
+  readonly updatedAt: number
+  /** Process-local continuation eligibility; never persisted. */
+  readonly activation: GoalActivation
+}
+
+/**
+ * The `goal` projection value: the current durable goal with its replay
+ * counters, exactly as the latest `goal/change` event carried them.
+ * Activation is process-local (never persisted) and deliberately absent —
+ * the projection reflects durable phase only.
+ */
+export interface GoalProjection {
+  /** Current durable goal snapshot (the CAS ref for mutations rides on it). */
+  readonly goal: GoalSnapshot
+  /** Highest admitted round number for this goal. */
+  readonly roundsStarted: number
+  /** Epoch milliseconds of the create mutation. */
+  readonly createdAt: number
+  /** Epoch milliseconds of the latest mutation. */
+  readonly updatedAt: number
+}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    /**
+     * The session's current goal (the latest `goal/change` whole value), or
+     * `null` before the first create and after a clear tombstone.
+     * Whole-value rule: every goal change carries the complete post-change
+     * state, so the fold is last-wins.
+     */
+    goal: GoalProjection | null
+  }
+}