@defrex/autobuild 0.8.0

package/packages/core/src/distribution.ts

@@ -0,0 +1,24 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Directory of this module. Bun exposes `import.meta.dir`; bundlers that
+ * embed the module (Next.js/Turbopack for the hosted service) provide only
+ * `import.meta.url`, so fall back to it rather than resolving from undefined
+ * at module evaluation time.
+ */
+function moduleDir(): string {
+  const dir = (import.meta as { dir?: unknown }).dir
+  if (typeof dir === 'string' && dir !== '') return dir
+  return dirname(fileURLToPath(import.meta.url))
+}
+
+/** Root of the installable `autobuild` compatibility distribution. */
+export function distributionRoot(): string {
+  return resolve(moduleDir(), '..', '..', '..')
+}
+
+/** Resolve a path owned by the root distribution. */
+export function distributionPath(...segments: string[]): string {
+  return resolve(distributionRoot(), ...segments)
+}

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

@@ -0,0 +1,201 @@
+/**
+ * The event catalog: envelope + payload schemas + per-type actor rules, and
+ * the single validation entry point every store adapter calls at append.
+ * This is where the ontology is *enforced*, not just described (SPEC §8).
+ */
+import {
+  actorSchema,
+  VIA_ACTOR_RULE,
+  viaOnNonHumanActor,
+  type Actor,
+  type ActorKind,
+} from './envelope'
+import { eventPayloadSchemas, isEventType, type EventPayload, type EventType } from './payloads'
+
+/**
+ * A stored event: envelope (SPEC §15.1) with a known type. `seq` is per-build
+ * and monotonic, `ts` is ISO-8601; both are store-assigned on append.
+ */
+export interface EventEnvelope<T extends EventType = EventType> {
+  build: string
+  seq: number
+  ts: string
+  actor: Actor
+  type: T
+  payload: EventPayload<T>
+}
+
+/** The discriminated union over every event type — what reducers consume. */
+export type AbEvent = { [T in EventType]: EventEnvelope<T> }[EventType]
+
+/** What a producer submits; the store assigns `seq`/`ts` (§15.1). */
+export interface EventWrite<T extends EventType = EventType> {
+  actor: Actor
+  type: T
+  payload: EventPayload<T>
+}
+
+/**
+ * Which actor kinds may emit each event type — the Actor column of the
+ * catalog tables in SPEC §15.3.
+ */
+export const allowedActorKinds: Record<EventType, readonly ActorKind[]> = {
+  'build.created': ['dispatcher', 'human'],
+  'build.completed': ['dispatcher'],
+  'runner.attached': ['kernel'],
+  'runner.setup-failed': ['kernel'],
+  'workspace.provisioned': ['dispatcher', 'kernel'],
+  'workspace.provision-started': ['dispatcher'],
+  'workspace.released': ['dispatcher', 'kernel'],
+  'execution.started': ['dispatcher'],
+  'execution.ended': ['dispatcher'],
+  'infrastructure.failed': ['dispatcher'],
+  'infrastructure.cleanup-attempted': ['dispatcher'],
+  'publication.requested': ['agent', 'kernel'],
+  // Only the dispatcher releases workspaces and settles publications (§15.7);
+  // the kernel never destroys one, so it never records a loss.
+  'publication.lost': ['dispatcher'],
+  'abort.remote-branch-deleted': ['dispatcher'],
+  'abort.local-branch-deleted': ['dispatcher'],
+  'abort.ticket-returned': ['dispatcher'],
+  'dispatch.failed': ['dispatcher'],
+  'dispatch.comment-posted': ['dispatcher'],
+
+  'build.pause-requested': ['human'],
+  'build.resume-requested': ['human'],
+  'build.abort-requested': ['human'],
+  'build.discard-requested': ['human'],
+  'build.auto-merge-requested': ['human'],
+  'build.auto-merge-cancelled': ['human'],
+  'build.paused': ['kernel'],
+  'build.resumed': ['kernel'],
+  'build.aborted': ['kernel', 'dispatcher'],
+
+  'spec.imported': ['dispatcher'],
+  'spec.authored': ['agent'],
+  'spec.revised': ['kernel'],
+
+  'session.started': ['kernel'],
+  'session.ended': ['kernel'],
+
+  'plan.started': ['kernel'],
+  'plan.completed': ['agent'],
+  'plan-review.started': ['kernel'],
+  'plan-review.verdict': ['agent'],
+  'implement.started': ['kernel'],
+  'implement.completed': ['agent', 'dispatcher'],
+  'code-review.started': ['kernel'],
+  'code-review.verdict': ['agent'],
+
+  'verify.started': ['kernel'],
+  'verify.completed': ['kernel', 'agent'],
+  'finalize.started': ['kernel'],
+  'finalize.completed': ['kernel'],
+  'finalize.step-completed': ['kernel', 'agent'],
+  'pr-attachment.designated': ['agent'],
+  'pr-attachment.hosted': ['kernel'],
+  'pr-attachment.reclaimed': ['dispatcher'],
+  'pr-attachment.reclaim-failed': ['dispatcher'],
+
+  'pr.auto-merge-enabled': ['kernel', 'dispatcher'],
+  'pr.auto-merge-disabled': ['kernel', 'dispatcher'],
+  'pr.merged': ['dispatcher'],
+  'pr.closed': ['dispatcher'],
+  'pr.conflicted': ['dispatcher'],
+  'reconcile.progress-checked': ['kernel'],
+  'reconcile.started': ['kernel'],
+  'reconcile.completed': ['agent', 'dispatcher'],
+
+  'observation.recorded': ['kernel', 'agent'],
+  'escalation.raised': ['agent', 'kernel', 'dispatcher'],
+  // Answering an escalation is always a deliberate human act. Historical
+  // dispatcher-authored retries remain reducible because replay does not
+  // revalidate already-persisted envelopes.
+  'escalation.answered': ['human'],
+  'phase.failed': ['kernel'],
+}
+
+/**
+ * Validation failures are agent feedback (D6): the message carries what was
+ * wrong and what would be accepted, so the in-session correction loop is
+ * immediate and cheap.
+ */
+export class EventValidationError extends Error {
+  constructor(
+    message: string,
+    readonly issues?: unknown,
+  ) {
+    super(message)
+    this.name = 'EventValidationError'
+  }
+}
+
+/**
+ * The single validation gate. Every store adapter MUST pass writes through
+ * here before appending — the contract tests enforce that they do.
+ */
+export function validateEventWrite(input: {
+  actor: unknown
+  type: string
+  payload: unknown
+}): EventWrite {
+  if (!isEventType(input.type)) {
+    throw new EventValidationError(
+      `unknown event type "${input.type}" — known types: ${Object.keys(eventPayloadSchemas).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 schema = eventPayloadSchemas[input.type]
+  const payloadResult = schema.safeParse(input.payload)
+  if (!payloadResult.success) {
+    throw new EventValidationError(
+      `invalid payload for "${input.type}": ${payloadResult.error.message}`,
+      payloadResult.error.issues,
+    )
+  }
+  if (input.type === 'escalation.raised') {
+    const escalation = payloadResult.data as EventPayload<'escalation.raised'>
+    if (
+      actor.kind === 'dispatcher' &&
+      (escalation.source !== 'policy' || escalation.policyCause !== 'infrastructure-failure-limit')
+    ) {
+      throw new EventValidationError(
+        'invalid dispatcher escalation: only policy/infrastructure-failure-limit may be raised outside the kernel',
+      )
+    }
+    if (escalation.source === 'policy' && escalation.policyCause === undefined) {
+      throw new EventValidationError(
+        'invalid payload for "escalation.raised": source "policy" requires a recognized policyCause',
+      )
+    }
+    if (escalation.source !== 'policy' && escalation.policyCause !== undefined) {
+      throw new EventValidationError(
+        `invalid payload for "escalation.raised": policyCause is only allowed when source is "policy", not ${JSON.stringify(escalation.source)}`,
+      )
+    }
+  }
+  return {
+    actor,
+    type: input.type,
+    payload: payloadResult.data,
+  } as EventWrite
+}

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

@@ -0,0 +1,59 @@
+/**
+ * The event envelope (SPEC §15.1). Every event in a build's append-only log
+ * shares this shape; the store assigns `seq` and `ts` so producers can't fake
+ * ordering.
+ */
+import { z } from 'zod'
+
+/** Delegated-write attribution (SPEC §15.1): when an agent acts for a person,
+ * the event still names the person as the human actor and may name the
+ * delegate, so an audit trail can distinguish "the operator did this" from
+ * "the operator's orchestrator session did this" or "an MCP client did this"
+ * forever. Only human actors may carry `via`, and only on build and
+ * repository events; session events are the delegate's own log. */
+export const viaSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('session'), id: z.string().min(1) }),
+  z.strictObject({ kind: z.literal('mcp'), client: z.string().min(1) }),
+])
+export type Via = z.infer<typeof viaSchema>
+
+export const actorSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('kernel') }),
+  z.strictObject({
+    kind: z.literal('agent'),
+    role: z.string().min(1),
+    session: z.string().min(1),
+  }),
+  z.strictObject({
+    kind: z.literal('human'),
+    user: z.string().min(1),
+    via: viaSchema.optional(),
+  }),
+  z.strictObject({ kind: z.literal('dispatcher') }),
+  z.strictObject({ kind: z.literal('ingester'), source: z.string().min(1) }),
+])
+export type Actor = z.infer<typeof actorSchema>
+export type ActorKind = Actor['kind']
+
+export const KERNEL: Actor = { kind: 'kernel' }
+export const DISPATCHER: Actor = { kind: 'dispatcher' }
+
+export function agentActor(role: string, session: string): Actor {
+  return { kind: 'agent', role, session }
+}
+
+export function humanActor(user: string, via?: Via): Actor {
+  return via === undefined ? { kind: 'human', user } : { kind: 'human', user, via }
+}
+
+/** The validation rule every catalog's gate names when a `via` rides on a
+ * non-human actor (the strict variants reject the key themselves, but their
+ * parse error would not say why it is forbidden). */
+export const VIA_ACTOR_RULE = 'only human actors may carry via'
+
+/** Raw-input check used before actor parsing: `via` on any non-human actor. */
+export function viaOnNonHumanActor(actor: unknown): boolean {
+  if (typeof actor !== 'object' || actor === null) return false
+  const candidate = actor as { kind?: unknown; via?: unknown }
+  return candidate.kind !== 'human' && candidate.via !== undefined
+}