@defrex/autobuild 0.12.0 → 0.14.0

package/packages/core/src/store/reducer-value-validation.ts

@@ -0,0 +1,96 @@
+import type { JsonValue } from './reducer-values'
+import shapes from './reducer-value-shapes.json'
+
+type Shape = {
+  kind: string
+  value?: unknown
+  items?: string | string[]
+  props?: Record<string, { type: string; optional: boolean }>
+  index?: string
+}
+const schemas: Record<string, Shape> = shapes.schemas
+
+/** Generated structural shapes include nested event payload unions, records,
+ * optional fields and literal discriminants. No accumulator is trusted merely
+ * because finish() happens to accept it. */
+export function validateAccumulator(name: string, value: unknown): boolean {
+  const root = (shapes.roots as Record<string, { acc: string }>)[name]
+  return root !== undefined && matches(root.acc, value)
+}
+export function validateReducerValue(name: string, value: unknown): boolean {
+  const root = (shapes.roots as Record<string, { value: string }>)[name]
+  return root !== undefined && matches(root.value, value)
+}
+function json(value: unknown): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') return Number.isFinite(value)
+  if (Array.isArray(value)) return value.every(json)
+  return (
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype &&
+    Object.values(value).every(json)
+  )
+}
+function matches(id: string, value: unknown): boolean {
+  const shape = schemas[id]!
+  switch (shape.kind) {
+    case 'json':
+      return json(value)
+    case 'undefined':
+      return value === undefined
+    case 'literal':
+      return value === shape.value
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value)
+    case 'string':
+      return typeof value === 'string'
+    case 'boolean':
+      return typeof value === 'boolean'
+    case 'union':
+      return (shape.items as string[]).some((item) => matches(item, value))
+    case 'array':
+      return Array.isArray(value) && value.every((item) => matches(shape.items as string, item))
+    case 'object': {
+      if (
+        value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype
+      )
+        return false
+      const record = value as Record<string, unknown>
+      for (const [key, prop] of Object.entries(shape.props!)) {
+        if (!(key in record) && prop.optional) continue
+        if (!matches(prop.type, record[key])) return false
+      }
+      return Object.keys(record).every(
+        (key) =>
+          Object.hasOwn(shape.props!, key) ||
+          (shape.index !== undefined && matches(shape.index, record[key])),
+      )
+    }
+    default:
+      return false
+  }
+}
+
+/** Existing optional object fields keep their ordinary JSON omission semantics.
+ * Collections, functions, nonfinite numbers and undefined array entries cannot
+ * silently become a different public contract during JSON serialization. */
+export function encodeReducerValue(value: unknown): JsonValue {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean')
+    return value as JsonValue
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (Array.isArray(value)) return value.map(encodeReducerValue)
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  )
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .map(([key, item]) => [key, encodeReducerValue(item)]),
+    )
+  throw new Error('reducer finished value is not plain JSON')
+}

package/packages/core/src/store/reducer-values.ts

@@ -0,0 +1,145 @@
+/** Named JSON answers over persisted incremental state. The event log remains authoritative. */
+import { z } from 'zod'
+import type { AbEvent } from '../events/catalog'
+import type { RepositoryEvent } from '../events/repository'
+import { REDUCERS } from '../kernel/reducer-registry'
+import type { IncrementalReducer } from '../kernel/incremental'
+import {
+  REDUCER_VALUE_SNAPSHOT_PREFIX,
+  type ReducerSnapshot,
+  type SnapshotScope,
+} from './snapshots'
+
+export const reducerValueRequestSchema = z
+  .object({
+    reducer: z.string().min(1).max(64),
+    args: z.record(z.string(), z.json()).optional(),
+  })
+  .strict()
+export type ReducerValueRequest = z.infer<typeof reducerValueRequestSchema>
+export type JsonValue = z.infer<ReturnType<typeof z.json>>
+export interface ReducerValue {
+  version: number
+  cursor: number
+  value: JsonValue
+}
+export const reducerValueSchema = z
+  .object({
+    version: z.number().int().positive(),
+    cursor: z.number().int().nonnegative(),
+    value: z.json(),
+  })
+  .strict()
+
+export interface ValueCatalogEntry {
+  scope: SnapshotScope['kind']
+  args: z.ZodType
+  validate(state: unknown): boolean
+  adapt(events: readonly (AbEvent | RepositoryEvent)[]): readonly unknown[]
+  value(state: unknown): JsonValue
+  // biome-ignore lint/suspicious/noExplicitAny: heterogeneous executable catalog
+  create(args: any): IncrementalReducer<any, any, any>
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value !== null && typeof value === 'object')
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
+      .join(',')}}`
+  return JSON.stringify(value)
+}
+
+export function resolveReducerValue(scope: SnapshotScope, input: ReducerValueRequest) {
+  const request = reducerValueRequestSchema.parse(input)
+  const registration = Object.hasOwn(REDUCERS, request.reducer)
+    ? REDUCERS[request.reducer]
+    : undefined
+  if (!registration) throw new Error(`unknown reducer "${request.reducer}"`)
+  const entry = registration.valueRead
+  if ('excluded' in entry)
+    throw new Error(`excluded reducer "${request.reducer}": ${entry.excluded}`)
+  if (entry.scope !== scope.kind) throw new Error(`wrong scope for reducer "${request.reducer}"`)
+  const args = entry.args.parse(request.args ?? {})
+  const reducer = entry.create(args)
+  const identity = canonical({ scope, reducer: request.reducer, version: reducer.version, args })
+  // v2 ignores checkpoints from the former client-writable key format.
+  const key = `${REDUCER_VALUE_SNAPSHOT_PREFIX}v2.${new Bun.CryptoHasher('sha256').update(identity).digest('hex').slice(0, 54)}`
+  return { name: request.reducer, reducer, identity, key, entry }
+}
+
+/** Raw cache reads and conditional repairs are private adapter operations: clients
+ * cannot submit a new accumulator through the value API. `token` identifies the
+ * exact row read, including malformed bytes that could not be decoded. */
+export interface ValueCacheRow {
+  snapshot: ReducerSnapshot
+  token: string
+}
+export interface ReducerValueStorage {
+  highWater(): Promise<number>
+  read(key: string): Promise<ValueCacheRow | null>
+  events(since: number, through: number): Promise<(AbEvent | RepositoryEvent)[]>
+  put(key: string, snapshot: ReducerSnapshot): Promise<boolean>
+  repair(key: string, observed: ValueCacheRow, snapshot: ReducerSnapshot): Promise<boolean>
+}
+
+export async function readReducerValue(
+  scope: SnapshotScope,
+  request: ReducerValueRequest,
+  storage: ReducerValueStorage,
+): Promise<ReducerValue> {
+  const { reducer, identity, key, entry } = resolveReducerValue(scope, request)
+  let boundary = await storage.highWater()
+  let row: ValueCacheRow | null = null
+  try {
+    row = await storage.read(key)
+  } catch {
+    /* unreadable cache is a miss */
+  }
+  // A concurrent reader may have persisted beyond our first boundary. Only a
+  // fresh authoritative boundary can establish ahead-of-log poison.
+  if (row && row.snapshot.cursor > boundary) boundary = await storage.highWater()
+  let acc = reducer.initial()
+  let cursor = 0
+  let valid = false
+  if (row) {
+    const { snapshot } = row
+    const state = snapshot.state as { identity?: unknown; acc?: unknown } | null
+    try {
+      valid =
+        snapshot.version === reducer.version &&
+        Number.isSafeInteger(snapshot.cursor) &&
+        snapshot.cursor >= 0 &&
+        snapshot.cursor <= boundary &&
+        state !== null &&
+        typeof state === 'object' &&
+        state.identity === identity &&
+        entry.validate(state.acc)
+    } catch {
+      valid = false // malformed nested cache data must never prevent replay
+    }
+    if (valid) {
+      acc = structuredClone(state!.acc)
+      cursor = snapshot.cursor
+    }
+  }
+  const delta = (await storage.events(cursor, boundary)).filter((event) => event.seq <= boundary)
+  for (const event of delta) {
+    if (event.seq !== cursor + 1) throw new Error('noncontiguous reducer log')
+    cursor = event.seq
+  }
+  if (cursor !== boundary) throw new Error('incomplete reducer log')
+  acc = reducer.advance(acc, entry.adapt(delta))
+  const value = entry.value(reducer.finish(acc))
+  if (!valid || delta.length > 0) {
+    const next = { version: reducer.version, cursor, state: { identity, acc } }
+    try {
+      if (row && !valid) await storage.repair(key, row, next)
+      else await storage.put(key, next)
+    } catch {
+      /* best-effort cache; log and reduction errors propagate */
+    }
+  }
+  return { version: reducer.version, cursor, value }
+}

package/packages/core/src/store/remote/client.ts

@@ -1,3 +1,9 @@
+import {
+  resolveReducerValue,
+  reducerValueSchema,
+  type ReducerValueRequest,
+  type ReducerValue,
+} from '../reducer-values'
 /**
  * RemoteBuildStore (SPEC §7.2 adapter 2): the client half of the remote
  * store — a full BuildStore over the wire protocol in protocol.ts. The
@@ -13,6 +19,8 @@
  * `subscribe` is the shared polling implementation over `getEvents(since)`
  * (§7.2); `close()` is a no-op — the server owns the backing store.
  */
+import { beginRepoTickResponseSchema, finishRepoTickResponseSchema } from './protocol'
+import type { RepoTickCompletion, RepoTickFinish } from '../types'
 import {
   EventValidationError,
   type AbEvent,
@@ -539,6 +547,17 @@ export class RemoteBuildStore implements BuildStore {
     )
   }
 
+  async getReducerValue(scope: SnapshotScope, request: ReducerValueRequest): Promise<ReducerValue> {
+    resolveReducerValue(scope, request)
+    const root = scope.kind === 'build' ? this.buildPath(scope.slug) : this.repoPath(scope.repo)
+    return this.requestJson(
+      'POST',
+      `${root}/reducer-values`,
+      reducerValueSchema,
+      request,
+    ) as Promise<ReducerValue>
+  }
+
   private snapshotPath(scope: SnapshotScope, reducer: string): string {
     const root = scope.kind === 'build' ? this.buildPath(scope.slug) : this.repoPath(scope.repo)
     return `${root}/snapshots/${encodeURIComponent(reducer)}`
@@ -822,6 +841,28 @@ export class RemoteBuildStore implements BuildStore {
     )
   }
 
+  async beginRepoTick(repo: string, holder: string): Promise<string | null> {
+    return this.requestJson(
+      'POST',
+      `${this.repoPath(repo)}/tick/begin`,
+      beginRepoTickResponseSchema,
+      { holder },
+    )
+  }
+  async finishRepoTick(
+    repo: string,
+    holder: string,
+    completion: RepoTickCompletion,
+    events: RepositoryEventWrite[],
+  ): Promise<RepoTickFinish | null> {
+    return (await this.requestJson(
+      'POST',
+      `${this.repoPath(repo)}/tick/finish`,
+      finishRepoTickResponseSchema,
+      { holder, completion, events },
+    )) as RepoTickFinish | null
+  }
+
   async claimRepoLease(repo: string, holder: string, ttlMs: number): Promise<boolean> {
     const result = await this.requestJson(
       'POST',

package/packages/core/src/store/remote/compatibility.ts

@@ -68,6 +68,8 @@ export const RELEASE_LINE_PROTOCOLS: Readonly<Record<string, string>> = {
   '0.10': '3',
   '0.11': '3',
   '0.12': '3',
+  // v0.13.0 shipped protocol 3. Protocol 4 requires the next minor line.
+  '0.13': '3',
 }
 
 export function clientIdentityError(

package/packages/core/src/store/remote/index.ts

@@ -35,3 +35,22 @@ export { delegateCredential } from './credentials'
 
 export { reduceBuild } from '../../kernel/reducer'
 export { reduceHarvest } from '../../kernel/harvest'
+
+export {
+  readReducerValue,
+  resolveReducerValue,
+  reducerValueRequestSchema,
+  reducerValueSchema,
+} from '../reducer-values'
+export type {
+  ReducerValue,
+  ReducerValueRequest,
+  ReducerValueStorage,
+  ValueCacheRow,
+} from '../reducer-values'
+
+export type { BuildDelegationFacts, HarvestDelegationFacts } from '../../kernel/service-facts'
+
+export { delegationFactKey } from '../../kernel/service-facts'
+
+export { assertPublicSnapshotReducer } from '../snapshots'

package/packages/core/src/store/remote/protocol.ts

@@ -24,6 +24,7 @@
  * Arbitrary computation over the assigned revisions inside `makeEvent`
  * (e.g. `rev + 1`, string interpolation) is unsupported by design.
  */
+import { repoTickCompletionSchema, repoTickObservationSchema } from '../repo-tick'
 import { reducerSnapshotWireSchema } from '../snapshots'
 import { z } from 'zod'
 import { actorSchema } from '../../events/envelope'
@@ -104,6 +105,7 @@ export const conditionalEventResponseSchema = eventEnvelopeWireSchema.nullable()
 
 export const ensureRepoBodySchema = z.object({ repo: z.string().min(1) })
 export const repositoryRecordWireSchema = z.object({
+  tick: repoTickObservationSchema.optional(),
   repo: z.string().min(1),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -475,3 +477,17 @@ export const delegateCredentialBodySchema = z.discriminatedUnion('kind', [
 ])
 export type DelegateCredentialTarget = z.infer<typeof delegateCredentialBodySchema>
 export const delegateCredentialResponseSchema = z.strictObject({ token: z.string().min(1) })
+
+export { reducerValueRequestSchema, reducerValueSchema } from '../reducer-values'
+export const beginRepoTickResponseSchema = z.iso.datetime().nullable()
+export const finishRepoTickBodySchema = z.object({
+  holder: z.string().min(1),
+  completion: repoTickCompletionSchema,
+  events: z.array(z.object({ actor: actorSchema, type: z.string(), payload: z.unknown() })),
+})
+export const finishRepoTickResponseSchema = z
+  .object({
+    observation: repoTickObservationSchema,
+    events: z.array(repositoryEventEnvelopeWireSchema),
+  })
+  .nullable()

package/packages/core/src/store/remote/version.ts

@@ -4,11 +4,13 @@ import manifest from '../../../../../package.json'
 export const AUTOBUILD_VERSION = manifest.version
 
 /** Wire compatibility version for the remote BuildStore protocol.
+ * Version 4: adds required fenced begin/finish tick operations and bounded
+ * repository tick telemetry.
  * Version 3 (AUT-521): the build-digest wire shape gains per-occurrence
  * observation timestamps and the `merged` fact — a breaking shape change,
  * so stale peers are rejected at handshake instead of failing mid-request
  * at schema parse. */
-export const REMOTE_STORE_PROTOCOL_VERSION = '3'
+export const REMOTE_STORE_PROTOCOL_VERSION = '4'
 
 export const AUTOBUILD_VERSION_HEADER = 'x-autobuild-version'
 export const REMOTE_STORE_PROTOCOL_VERSION_HEADER = 'x-autobuild-protocol-version'

package/packages/core/src/store/repo-state-events.ts

@@ -142,7 +142,7 @@ export const repositoryStateEventsReducer: IncrementalReducer<
  * `RepositoryStateEventsAcc` it prunes on every `dispatcher.run-started`
  * (everything before the new anchor that is not durable leaves the tail), which
  * is exact for seq-ordered input — the only input a real journal produces — and
- * keeps the accumulator bounded, so it is the one a snapshot stores. */
+ * holds the tail only in process memory. It is never persisted as a snapshot. */
 export interface JournalViewAcc {
   anchor?: number
   retained: RepositoryEvent[]

package/packages/core/src/store/repo-tick.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod'
+import { EventValidationError } from '../events/catalog'
+import {
+  dispatcherStatusEventPayloadSchemas,
+  validateRepositoryEventWrite,
+  type RepositoryEventWrite,
+} from '../events/repository'
+import type { RepoTickCompletion } from './types'
+
+export const repoTickCompletionSchema = z.discriminatedUnion('outcome', [
+  z.object({
+    outcome: z.literal('completed'),
+    counters: dispatcherStatusEventPayloadSchemas['dispatcher.tick-completed'].shape.counters,
+  }),
+  z.object({ outcome: z.literal('failed'), error: z.string().min(1) }),
+])
+export const repoTickObservationSchema = z.object({
+  run: z.string().min(1),
+  open: z.object({ startedAt: z.iso.datetime() }).optional(),
+  finished: z
+    .intersection(
+      repoTickCompletionSchema,
+      z.object({
+        run: z.string().min(1),
+        startedAt: z.iso.datetime(),
+        completedAt: z.iso.datetime(),
+      }),
+    )
+    .optional(),
+})
+
+/** Only a matching start and terminal boundary may ride the atomic finish. */
+export function validateTickFinish(
+  holder: string,
+  completion: RepoTickCompletion,
+  events: RepositoryEventWrite[],
+) {
+  const parsed = repoTickCompletionSchema.parse(completion)
+  const validated = events.map(validateRepositoryEventWrite)
+  if (validated.length === 0 && completion.outcome === 'completed') return validated
+  if (validated.length !== 2)
+    throw new EventValidationError('tick finish requires start and terminal boundaries')
+  const [start, end] = validated
+  if (
+    start!.type !== 'dispatcher.tick-started' ||
+    end!.type !==
+      (completion.outcome === 'completed'
+        ? 'dispatcher.tick-completed'
+        : 'dispatcher.tick-failed') ||
+    validated.some(
+      (e) => e.actor.kind !== 'dispatcher' || !('run' in e.payload) || e.payload.run !== holder,
+    )
+  ) {
+    throw new EventValidationError('invalid tick finish boundaries')
+  }
+  if (
+    end!.type === 'dispatcher.tick-failed' &&
+    completion.outcome === 'failed' &&
+    dispatcherStatusEventPayloadSchemas['dispatcher.tick-failed'].parse(end!.payload).error !==
+      completion.error
+  )
+    throw new EventValidationError('tick error mismatch')
+  if (
+    end!.type === 'dispatcher.tick-completed' &&
+    completion.outcome === 'completed' &&
+    JSON.stringify(
+      dispatcherStatusEventPayloadSchemas['dispatcher.tick-completed'].parse(end!.payload).counters,
+    ) !== JSON.stringify(parsed.outcome === 'completed' ? parsed.counters : {})
+  )
+    throw new EventValidationError('tick counters mismatch')
+  return validated
+}

package/packages/core/src/store/session-handle.ts

@@ -1,3 +1,4 @@
+import type { ReducerValueRequest, ReducerValue } from './reducer-values'
 import type { ReducerSnapshot, SnapshotScope } from './snapshots'
 import type { EventType } from '../events/payloads'
 import type { EventWrite } from '../events/catalog'
@@ -175,6 +176,18 @@ export function createSessionScopedStore(store: BuildStore, scope: string): Sess
     getRepoHighWater(repo: string): Promise<number> {
       return Promise.reject(new SessionScopeError(scope, 'getRepoHighWater', repo))
     },
+    async getReducerValue(
+      target: SnapshotScope,
+      _request: ReducerValueRequest,
+    ): Promise<ReducerValue> {
+      return Promise.reject(
+        new SessionScopeError(
+          scope,
+          'getReducerValue',
+          target.kind === 'build' ? target.slug : target.repo,
+        ),
+      )
+    },
     getReducerSnapshot(
       target: SnapshotScope,
       _reducer: string,
@@ -262,6 +275,12 @@ export function createSessionScopedStore(store: BuildStore, scope: string): Sess
     claimRepoLease(repo: string, _holder: string, _ttlMs: number): Promise<boolean> {
       return Promise.reject(new SessionScopeError(scope, 'claimRepoLease', repo))
     },
+    beginRepoTick(repo: string) {
+      return Promise.reject(new SessionScopeError(scope, 'beginRepoTick', repo))
+    },
+    finishRepoTick(repo: string) {
+      return Promise.reject(new SessionScopeError(scope, 'finishRepoTick', repo))
+    },
     heartbeatRepo(repo: string, _holder: string): Promise<boolean> {
       return Promise.reject(new SessionScopeError(scope, 'heartbeatRepo', repo))
     },

package/packages/core/src/store/snapshots.ts

@@ -36,6 +36,16 @@ export const reducerSnapshotWireSchema = z.object({
  * path segment and a SQL key. */
 export const SNAPSHOT_REDUCER_NAME = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/
 
+/** Value checkpoints are written only by the adapter's private reduction path.
+ * Generic snapshot clients must never supply state used for named answers. */
+export const REDUCER_VALUE_SNAPSHOT_PREFIX = 'value.'
+
+export function assertPublicSnapshotReducer(reducer: string): void {
+  if (reducer.startsWith(REDUCER_VALUE_SNAPSHOT_PREFIX)) {
+    throw new Error('reserved reducer value snapshot namespace')
+  }
+}
+
 export function snapshotScopeKey(scope: SnapshotScope): string {
   return scope.kind === 'build' ? `build:${scope.slug}` : `repo:${scope.repo}`
 }