@defrex/autobuild 0.8.0

package/packages/core/src/events/sessions.ts

@@ -0,0 +1,180 @@
+/**
+ * Operator-session event catalog (SPEC §7.1.1). Operator sessions are a third
+ * BuildStore resource kind alongside builds and the repository journal: an
+ * orchestrator conversation is durable state, but it is neither a build nor a
+ * repository fact. The catalog is closed and validated separately from the
+ * build and repository catalogs, so no build reducer can interpret session
+ * events — the same separation the repository journal has.
+ *
+ * Sessions are hosted-only: local installs interact through the CLI and
+ * dashboard and never create one. Nothing in this module encodes this
+ * repository's specifics.
+ */
+import { z } from 'zod'
+import { EventValidationError } from './catalog'
+import {
+  actorSchema,
+  VIA_ACTOR_RULE,
+  viaOnNonHumanActor,
+  type Actor,
+  type ActorKind,
+} from './envelope'
+
+const positiveInt = z.number().int().positive()
+
+const empty = z.strictObject({})
+
+/** The trigger that started a turn: a human message or a wake event. */
+const turnTriggerSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('message'), messageSeq: positiveInt }),
+  z.strictObject({
+    kind: z.literal('wake'),
+    build: z.string().min(1),
+    seq: positiveInt,
+    type: z.string().min(1),
+  }),
+])
+
+/** Matches the transcript usage shape (harvest.session.ended, §15.3). */
+const usageSchema = z.strictObject({
+  inputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative(),
+  turns: z.number().int().nonnegative().optional(),
+})
+
+export const sessionEventPayloadSchemas = {
+  /** The fact of creation; the session record carries the same title. */
+  'session.created': z.strictObject({ title: z.string().min(1).optional() }),
+  /** A human operator's message. */
+  'message.posted': z.strictObject({ text: z.string().min(1) }),
+  /** Which attention events may start a turn. Possibly empty: empty means
+   * no wake sources (message-only). */
+  'session.wake-set': z.strictObject({
+    globs: z.array(z.string().min(1)).max(100),
+  }),
+  /** The (later) turn runner's start of one turn on its stream. */
+  'turn.started': z.strictObject({
+    turn: z.string().min(1),
+    stream: z.string().min(1),
+    trigger: turnTriggerSchema,
+  }),
+  /** A turn was suspended for budget or for an approval. */
+  'turn.suspended': z.strictObject({
+    turn: z.string().min(1),
+    cause: z.enum(['budget', 'approval']),
+  }),
+  /** The runner's acknowledgement that a suspended turn continues. */
+  'turn.resumed': z.strictObject({ turn: z.string().min(1) }),
+  /** The turn asks its human to approve one tool call. */
+  'approval.requested': z.strictObject({
+    turn: z.string().min(1),
+    toolCallId: z.string().min(1),
+    toolName: z.string().min(1),
+    input: z.record(z.string(), z.unknown()),
+  }),
+  /** The human's decision on one requested approval. */
+  'approval.answered': z.strictObject({
+    turn: z.string().min(1),
+    toolCallId: z.string().min(1),
+    decision: z.enum(['approve', 'deny']),
+  }),
+  /** One turn finished. */
+  'turn.completed': z.strictObject({ turn: z.string().min(1), usage: usageSchema }),
+  /** One turn failed. */
+  'turn.failed': z.strictObject({ turn: z.string().min(1), error: z.string().min(1) }),
+  /** Terminal. The session is read-only afterwards. */
+  'session.archived': empty,
+} as const
+
+export type SessionEventType = keyof typeof sessionEventPayloadSchemas
+export const SESSION_EVENT_TYPES = Object.keys(sessionEventPayloadSchemas) as SessionEventType[]
+export type SessionEventPayload<T extends SessionEventType> = z.infer<
+  (typeof sessionEventPayloadSchemas)[T]
+>
+
+export interface SessionEventEnvelope<T extends SessionEventType = SessionEventType> {
+  session: string
+  seq: number
+  ts: string
+  actor: Actor
+  type: T
+  payload: SessionEventPayload<T>
+}
+
+export type SessionEvent = {
+  [T in SessionEventType]: SessionEventEnvelope<T>
+}[SessionEventType]
+
+export interface SessionEventWrite<T extends SessionEventType = SessionEventType> {
+  actor: Actor
+  type: T
+  payload: SessionEventPayload<T>
+}
+
+/** Which actor kinds may emit each event type — the session catalog's Actor
+ * column, enforced at validation exactly as for builds (§15.3). Humans create,
+ * message, configure wakes, answer approvals, and archive; the agent (the
+ * embedded orchestrator's turn runner) owns the turn lifecycle. */
+const allowedActorKinds: Record<SessionEventType, readonly ActorKind[]> = {
+  'session.created': ['human'],
+  'message.posted': ['human'],
+  'session.wake-set': ['human'],
+  'approval.answered': ['human'],
+  'session.archived': ['human'],
+  'turn.started': ['agent'],
+  'turn.suspended': ['agent'],
+  'turn.resumed': ['agent'],
+  'approval.requested': ['agent'],
+  'turn.completed': ['agent'],
+  'turn.failed': ['agent'],
+}
+
+export function isSessionEventType(value: string): value is SessionEventType {
+  return Object.hasOwn(sessionEventPayloadSchemas, value)
+}
+
+/**
+ * The session catalog's single validation gate. Every store adapter MUST pass
+ * session writes through here before appending, with the same exact strictness
+ * as the build and repository gates (D6).
+ */
+export function validateSessionEventWrite(input: {
+  actor: unknown
+  type: string
+  payload: unknown
+}): SessionEventWrite {
+  if (!isSessionEventType(input.type)) {
+    throw new EventValidationError(
+      `unknown session event type "${input.type}" — known types: ${SESSION_EVENT_TYPES.join(', ')}`,
+    )
+  }
+  if (viaOnNonHumanActor(input.actor)) {
+    throw new EventValidationError(VIA_ACTOR_RULE)
+  }
+  const actorResult = actorSchema.safeParse(input.actor)
+  if (!actorResult.success) {
+    throw new EventValidationError(
+      `invalid actor for "${input.type}": ${actorResult.error.message}`,
+      actorResult.error.issues,
+    )
+  }
+  const actor = actorResult.data
+  const allowed = allowedActorKinds[input.type]
+  if (!allowed.includes(actor.kind)) {
+    throw new EventValidationError(
+      `actor kind "${actor.kind}" may not emit "${input.type}" (allowed: ${allowed.join(', ')})`,
+    )
+  }
+  const result = sessionEventPayloadSchemas[input.type].safeParse(input.payload)
+  if (!result.success) {
+    throw new EventValidationError(
+      `invalid payload for "${input.type}": ${result.error.message}`,
+      result.error.issues,
+    )
+  }
+  return {
+    actor,
+    type: input.type,
+    payload: result.data,
+  } as SessionEventWrite
+}

package/packages/core/src/harvest/schema.ts

@@ -0,0 +1,147 @@
+/**
+ * Frozen structured values shared by the harvest kernel, CLI, skills, and
+ * repository journal. Harvest operates on observation occurrences, not on an
+ * observation id alone: event sequence numbers are only monotonic within one
+ * build, so `{build, seq}` is the canonical identity.
+ */
+import { z } from 'zod'
+import { observationKindSchema, ticketRefSchema } from '../ontology'
+
+export const occurrenceKeySchema = z.strictObject({
+  build: z.string().min(1),
+  seq: z.number().int().positive(),
+})
+export type OccurrenceKey = z.infer<typeof occurrenceKeySchema>
+
+export function occurrenceKey(key: OccurrenceKey): string {
+  return `${key.build}:${key.seq}`
+}
+
+export const harvestObservationSchema = z.strictObject({
+  occurrence: occurrenceKeySchema,
+  id: z.string().min(1),
+  kind: observationKindSchema,
+  summary: z.string().min(1),
+  files: z.array(z.string()).optional(),
+  refs: z.array(z.string()).optional(),
+  ts: z.string().min(1),
+  ticket: ticketRefSchema.optional(),
+})
+export type HarvestObservation = z.infer<typeof harvestObservationSchema>
+
+/** The durable reason a Harvest snapshot crossed repository pressure. */
+export const harvestTriggerSchema = z.enum(['count', 'drift', 'both'])
+export type HarvestTrigger = z.infer<typeof harvestTriggerSchema>
+
+/** Source-aware lifecycle visibility for distinct tickets that originated the
+ * observations in a scan. Foreign-source refs remain visible but are never
+ * sent to the repository's configured TicketSource. */
+export const harvestOriginatingTicketSchema = z.strictObject({
+  ticket: ticketRefSchema,
+  sourceMatches: z.boolean(),
+  exists: z.boolean(),
+  resolved: z.boolean(),
+})
+export type HarvestOriginatingTicket = z.infer<typeof harvestOriginatingTicketSchema>
+
+/** Filing records both meanings even when one id is simultaneously declared
+ * by the agent and automatically derived from an originating ticket. */
+export const harvestBlockerProvenanceSchema = z.strictObject({
+  declared: z.array(z.string().min(1)),
+  derived: z.array(z.string().min(1)),
+})
+export type HarvestBlockerProvenance = z.infer<typeof harvestBlockerProvenanceSchema>
+
+/** Prior proposals are semantic-dedup context for the synthesizer. The source
+ * owns lifecycle resolution; harvest only reports the returned facts. */
+export const harvestLedgerTicketSchema = z.strictObject({
+  proposalKey: z.string().min(1),
+  ticket: ticketRefSchema,
+  exists: z.boolean(),
+  resolved: z.boolean(),
+  title: z.string().optional(),
+  body: z.string().optional(),
+})
+export type HarvestLedgerTicket = z.infer<typeof harvestLedgerTicketSchema>
+
+export const harvestScanPacketSchema = z.strictObject({
+  repo: z.string().min(1),
+  run: z.string().min(1),
+  observations: z.array(harvestObservationSchema).min(1),
+  originatingTickets: z.array(harvestOriginatingTicketSchema).default([]),
+  ledger: z.array(harvestLedgerTicketSchema).default([]),
+})
+export type HarvestScanPacket = z.infer<typeof harvestScanPacketSchema>
+
+const proposalMembers = z.array(occurrenceKeySchema).min(1)
+
+export const harvestCreateProposalSchema = z.strictObject({
+  action: z.literal('create'),
+  title: z.string().min(1),
+  /** The prose for the rendered `What and why` section. */
+  whatWhy: z.string().min(1),
+  acceptanceCriteria: z.array(z.string().min(1)).min(1),
+  /** Explicit even when there is little to exclude. */
+  outOfScope: z.array(z.string().min(1)).min(1),
+  /** Source-local ticket ids that must complete before this work can start. */
+  blockedBy: z
+    .array(
+      z
+        .string()
+        .min(1)
+        .refine((id) => id.trim().length > 0, 'blocker id must be nonblank'),
+    )
+    .optional(),
+  observations: proposalMembers,
+})
+
+export const harvestJoinProposalSchema = z.strictObject({
+  action: z.literal('join'),
+  ticket: ticketRefSchema,
+  observations: proposalMembers,
+  reason: z.string().min(1),
+})
+
+export const harvestSuppressProposalSchema = z.strictObject({
+  action: z.literal('suppress'),
+  observations: proposalMembers,
+  reason: z.string().min(1),
+})
+
+export const harvestProposalSchema = z.discriminatedUnion('action', [
+  harvestCreateProposalSchema,
+  harvestJoinProposalSchema,
+  harvestSuppressProposalSchema,
+])
+export type HarvestProposal = z.infer<typeof harvestProposalSchema>
+
+export const harvestProposalSetSchema = z.strictObject({
+  proposals: z.array(harvestProposalSchema).min(1),
+})
+export type HarvestProposalSet = z.infer<typeof harvestProposalSetSchema>
+
+export const harvestDispositionSchema = z.strictObject({
+  occurrence: occurrenceKeySchema,
+  action: z.enum(['filed', 'joined', 'suppressed']),
+  proposalKey: z.string().min(1).optional(),
+  ticket: ticketRefSchema.optional(),
+  reason: z.string().min(1).optional(),
+})
+export type HarvestDisposition = z.infer<typeof harvestDispositionSchema>
+
+/** Stable, prose-free summary of proposal work still pending when automatic
+ * recovery is exhausted. The released occurrence list remains authoritative;
+ * these descriptors let status name reviewed proposal clusters without
+ * loading an artifact. */
+export const harvestPendingProposalSchema = z.strictObject({
+  proposalKey: z.string().min(1),
+  action: z.enum(['create', 'join', 'suppress']),
+  observations: z.array(occurrenceKeySchema).min(1),
+})
+export type HarvestPendingProposal = z.infer<typeof harvestPendingProposalSchema>
+
+export const harvestStepSchema = z.enum(['scan', 'synthesize', 'review', 'file'])
+export type HarvestStep = z.infer<typeof harvestStepSchema>
+
+export const harvestStatusSchema = z.enum(['running', 'completed', 'escalated', 'failed'])
+export type HarvestStatus = z.infer<typeof harvestStatusSchema>

package/packages/core/src/ids.ts

@@ -0,0 +1,45 @@
+/**
+ * Id stamping. Finding, observation, and escalation ids are kernel-assigned
+ * at deposit (§15.4) — agents never self-assign them. Injectable so tests
+ * are deterministic.
+ */
+export type IdSource = (prefix: string) => string
+
+/** UUID v4 allocation is separate from short kernel ids: callers that need
+ * crash-stable UUIDs must reserve the generated value in durable state. */
+export type UuidSource = () => string
+
+/** Platform-backed UUID v4 allocation; no hand-rolled UUID bit shaping. */
+export function randomUuids(): UuidSource {
+  return () => crypto.randomUUID()
+}
+
+/** e.g. `f_3a91c07b` — 4 random bytes, hex. */
+export function randomIds(): IdSource {
+  return (prefix) => {
+    const bytes = new Uint8Array(4)
+    crypto.getRandomValues(bytes)
+    const hex = [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')
+    return `${prefix}_${hex}`
+  }
+}
+
+/** Deterministic ids for tests: `f_1`, `f_2`, … (counter per prefix). */
+export function sequentialIds(): IdSource {
+  const counters = new Map<string, number>()
+  return (prefix) => {
+    const next = (counters.get(prefix) ?? 0) + 1
+    counters.set(prefix, next)
+    return `${prefix}_${next}`
+  }
+}
+
+/** Deterministic UUID v4 values for integration harnesses. The version and
+ * variant nibbles remain valid while the final 48 bits carry the sequence. */
+export function sequentialUuids(): UuidSource {
+  let next = 0
+  return () => {
+    next += 1
+    return `00000000-0000-4000-8000-${next.toString(16).padStart(12, '0')}`
+  }
+}