@defrex/autobuild 0.11.0 → 0.13.0

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

@@ -1,3 +1,5 @@
+import { prepareAssetSnapshots } from './ticket-asset-snapshots'
+import { MemoryBuildStore } from './memory'
 /**
  * Reusable contract suites for the BuildStore seam (SPEC §7). The in-memory
  * adapter's behavior *is* the contract; every adapter — SQLite (§7.2.1),
@@ -2514,7 +2516,7 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
       async function pinnedBuild(
         store: BuildStore,
         slug: string,
-        assets: ReturnType<typeof pinOf>[],
+        assets: import('../events/payloads').PinnedAsset[],
       ): Promise<void> {
         const created = buildCreatedWrite()
         await store.createBuild({
@@ -2523,6 +2525,35 @@ export function describeBuildStoreContract(name: string, factory: BuildStoreFact
         })
       }
 
+      test('snapshot pins read independent bytes, historical revisions and scoped access', async () => {
+        await withStore(factory, undefined, async (store) => {
+          const source = new MemoryBuildStore()
+          await source.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'remote one'))
+          await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'local conflict'))
+          const pins = await prepareAssetSnapshots(source, store, REPO, 'TICK-1')
+          await pinnedBuild(store, 'snapshot-pin', pins)
+          await source.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'remote two'))
+          const newer = await prepareAssetSnapshots(source, store, REPO, 'TICK-1')
+          await store.append('snapshot-pin', {
+            actor: KERNEL,
+            type: 'spec.revised',
+            payload: { artifact: { kind: 'spec', rev: 1 }, escalation: 1, assets: newer },
+          })
+          await source.removeTicketAsset(REPO, 'TICK-1', 'design', 'a.txt')
+          expect(text(await store.getPinnedTicketAsset('snapshot-pin', 'design', 'a.txt'))).toBe(
+            'remote two',
+          )
+          expect(text(await store.getPinnedTicketAsset('snapshot-pin', 'design', 'a.txt', 0))).toBe(
+            'remote one',
+          )
+          expect(await store.getPinnedTicketAsset('snapshot-pin', 'design', 'a.txt', 2)).toBeNull()
+          const scoped = store.scopeBuild('snapshot-pin')
+          expect(text(await scoped.getPinnedTicketAsset('snapshot-pin', 'design', 'a.txt'))).toBe(
+            'remote two',
+          )
+        })
+      })
+
       test('reads the pinned revision after the ticket replaces and then removes the asset', async () => {
         await withStore(factory, undefined, async (store) => {
           const v0 = await store.putTicketAsset(REPO, 'TICK-1', file('a.txt', 'one'))

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

@@ -2036,7 +2036,7 @@ export class SqliteBuildStore implements BuildStore {
             return { stale: false, record: this.toStreamRecord(this.requireStream(streamId)) }
           },
         )
-        if (!committed.stale) return committed.record
+        if (committed.stale === false) return committed.record
         // A foreign appender landed inside the prepare window; loop and
         // re-prepare from the newer chunk set so its acknowledged chunk is
         // not omitted from the finalized artifact.

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

@@ -578,7 +578,7 @@ export class RemoteBuildStore implements BuildStore {
 
   async getRepoHighWater(repo: string): Promise<number> {
     // Additive route beside `state-events`; the store service and client
-    // ship in version lockstep, so no protocol bump.
+    // retain this additive route throughout the supported client window.
     return this.requestJson('GET', `${this.repoPath(repo)}/high-water`, repoHighWaterSchema).then(
       (body) => (body as { seq: number }).seq,
     )

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

@@ -0,0 +1,90 @@
+import semver from 'semver'
+import { z } from 'zod'
+import { AUTOBUILD_VERSION, REMOTE_STORE_PROTOCOL_VERSION } from './version'
+
+/** Stable releases only: prefixes, whitespace, prereleases and build suffixes are not identities. */
+export function stableVersion(value: unknown): semver.SemVer | undefined {
+  if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value)) return undefined
+  const parsed = semver.parse(value)
+  return parsed && parsed.version === value ? parsed : undefined
+}
+
+const stableVersionSchema = z.string().refine((value) => stableVersion(value) !== undefined)
+export const supportedClientRangeSchema = z
+  .strictObject({
+    minVersion: stableVersionSchema,
+    maxVersionExclusive: stableVersionSchema,
+  })
+  .refine((range) => semver.lt(range.minVersion, range.maxVersionExclusive))
+export type SupportedClientRange = z.infer<typeof supportedClientRangeSchema>
+
+/** A major starts a new family: X.0 has one line, X.1 two, X.2+ three. */
+export function supportedClientRange(serviceVersion = AUTOBUILD_VERSION): SupportedClientRange {
+  const version = stableVersion(serviceVersion)
+  if (!version) throw new Error('service must have a stable release version')
+  return {
+    minVersion: `${version.major}.${Math.max(0, version.minor - 2)}.0`,
+    maxVersionExclusive: `${version.major}.${version.minor + 1}.0`,
+  }
+}
+
+export function classifyClient(
+  version: unknown,
+  range: SupportedClientRange,
+): 'supported' | 'older' | 'newer' | 'invalid' {
+  const parsed = stableVersion(version)
+  if (!parsed) return 'invalid'
+  if (semver.lt(parsed, range.minVersion)) return 'older'
+  if (semver.gte(parsed, range.maxVersionExclusive)) return 'newer'
+  return 'supported'
+}
+
+export function formatClientRange(range: SupportedClientRange): string {
+  return `>=${range.minVersion} <${range.maxVersionExclusive}`
+}
+
+export function compatibilityAdvice(
+  client: unknown,
+  serviceVersion: string,
+  range: SupportedClientRange,
+): string | undefined {
+  const classification = classifyClient(client, range)
+  const description = `service Autobuild ${serviceVersion} supports clients ${formatClientRange(range)}`
+  if (classification === 'supported') return undefined
+  if (classification === 'newer') {
+    const version = stableVersion(client)!
+    return `${description}; upgrade the service to at least ${version.major}.${version.minor}.0 before upgrading projects (service first)`
+  }
+  if (classification === 'older')
+    return `${description}; upgrade the project's Autobuild into ${formatClientRange(range)}`
+  return `${description}; supply a stable Autobuild client version`
+}
+
+/** Retain these wire identities and handlers until their lines leave the window.
+ * Historical lines require explicit entries; the service's own line uses its
+ * current protocol identity. Unknown historical protocols fail closed. */
+export const RELEASE_LINE_PROTOCOLS: Readonly<Record<string, string>> = {
+  '0.9': '3',
+  '0.10': '3',
+  '0.11': '3',
+  '0.12': '3',
+}
+
+export function clientIdentityError(
+  client: string | null,
+  protocol: string | null,
+  serviceVersion = AUTOBUILD_VERSION,
+  serviceProtocol = REMOTE_STORE_PROTOCOL_VERSION,
+): string | undefined {
+  const range = supportedClientRange(serviceVersion)
+  const service = stableVersion(serviceVersion)!
+  const advice = compatibilityAdvice(client, serviceVersion, range)
+  const parsed = stableVersion(client)
+  const expected =
+    parsed &&
+    (parsed.major === service.major && parsed.minor === service.minor
+      ? serviceProtocol
+      : RELEASE_LINE_PROTOCOLS[`${parsed.major}.${parsed.minor}`])
+  if (!advice && expected !== undefined && protocol === expected) return undefined
+  return `remote store version mismatch: client Autobuild ${client ?? '(missing)'} protocol ${protocol ?? '(missing)'}; server Autobuild ${serviceVersion} protocol ${serviceProtocol}; ${advice ?? `supported clients ${formatClientRange(range)}; unsupported protocol identity`}`
+}

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

@@ -0,0 +1,28 @@
+import { delegateCredentialResponseSchema, type DelegateCredentialTarget } from './protocol'
+import {
+  AUTOBUILD_VERSION,
+  AUTOBUILD_VERSION_HEADER,
+  REMOTE_STORE_PROTOCOL_VERSION,
+  REMOTE_STORE_PROTOCOL_VERSION_HEADER,
+} from './version'
+
+/** Fail closed: a remote execution must never fall back to its parent token. */
+export async function delegateCredential(
+  storeRef: string,
+  token: string | undefined,
+  target: DelegateCredentialTarget,
+): Promise<string> {
+  if (!token) throw new Error('credential delegation requires parent authority')
+  const response = await fetch(`${storeRef.replace(/\/$/, '')}/credentials/delegate`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json',
+      [AUTOBUILD_VERSION_HEADER]: AUTOBUILD_VERSION,
+      [REMOTE_STORE_PROTOCOL_VERSION_HEADER]: REMOTE_STORE_PROTOCOL_VERSION,
+    },
+    body: JSON.stringify(target),
+  })
+  if (!response.ok) throw new Error(`credential delegation refused (${response.status})`)
+  return delegateCredentialResponseSchema.parse(await response.json()).token
+}

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

@@ -4,7 +4,13 @@
 export { AuthError, RemoteBuildStore } from './client'
 export type { RemoteBuildStoreOptions, RemoteStoreIdentity } from './client'
 export { mintToken, tokenResource, verifyToken } from './token'
-export type { OperatorTokenScope, TokenScope } from './token'
+export type {
+  OperatorTokenScope,
+  InternalOperatorTokenScope,
+  AdminTokenScope,
+  TokenScope,
+  DelegatedTokenScope,
+} from './token'
 export {
   AUTOBUILD_VERSION,
   AUTOBUILD_VERSION_HEADER,
@@ -22,3 +28,10 @@ export type { SessionEvent, SessionEventWrite } from '../../events/sessions'
 export type { RepositoryEvent, RepositoryEventWrite } from '../../events/repository'
 export { SNAPSHOT_REDUCER_NAME } from '../snapshots'
 export type { ReducerSnapshot, SnapshotScope } from '../snapshots'
+
+export * from './compatibility'
+
+export { delegateCredential } from './credentials'
+
+export { reduceBuild } from '../../kernel/reducer'
+export { reduceHarvest } from '../../kernel/harvest'

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

@@ -450,3 +450,28 @@ export function substitutePlaceholderRefs(
   }
   return value
 }
+
+/** Issuance is an authentication operation, separate from the BuildStore port. */
+export const delegateCredentialBodySchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('build-runner'), id: z.string().min(1) }),
+  z.strictObject({
+    kind: z.literal('build-phase'),
+    id: z.string().min(1),
+    session: z.string().min(1),
+  }),
+  z.strictObject({
+    kind: z.literal('harvest-runner'),
+    execution: z.string().min(1),
+    repo: z.string().min(1),
+    id: z.string().min(1),
+    leaseHolder: z.string().min(1),
+  }),
+  z.strictObject({
+    kind: z.literal('harvest-phase'),
+    repo: z.string().min(1),
+    id: z.string().min(1),
+    session: z.string().min(1),
+  }),
+])
+export type DelegateCredentialTarget = z.infer<typeof delegateCredentialBodySchema>
+export const delegateCredentialResponseSchema = z.strictObject({ token: z.string().min(1) })

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

@@ -1,13 +1,7 @@
-/**
- * HMAC-scoped store tokens (SPEC §8.1 [D8]): "the token is scoped to this
- * build and session — an agent physically cannot append to another build's
- * log or read another build's artifacts". Least privilege comes from the
- * runner minting a narrow token, not from prompt instructions.
- *
- * A token is `base64url(JSON scope) + '.' + base64url(hmac-sha256(secret,
- * payload))`. The scope IS the token — the server keeps no session state;
- * it verifies the signature (timing-safe) and the expiry, then trusts the
- * embedded scope.
+/** Signed lifecycle-bound execution grants, internal owner delegation and admin.
+ * Historical resource/deployment/operator scopes remain decodable for tests
+ * and migration diagnostics; hosted machine gates reject those retired forms.
+ * Project credentials are opaque stored secrets, not these stateless tokens.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto'
 import { z } from 'zod'
@@ -52,8 +46,35 @@ export interface DeploymentTokenScope {
   exp: number
 }
 
-/** Legacy scopes remain valid on their existing routes. */
+/** Includes retired wire shapes for recognition, never server authorization. */
+export interface InternalOperatorTokenScope {
+  version: 1
+  internalOperator: { user: string; repo: string }
+  exp: number
+  via?: Via
+}
+export interface AdminTokenScope {
+  version: 1
+  ownerAdmin: { user: string }
+  exp: number
+}
+export interface DelegatedTokenScope {
+  version: 2
+  delegation: {
+    repo: string
+    kind: 'build-runner' | 'build-phase' | 'harvest-runner' | 'harvest-phase'
+    id: string
+    anchor: number
+    session?: string
+    execution?: string
+    leaseHolder?: string
+  }
+}
+
 export type TokenScope =
+  | DelegatedTokenScope
+  | InternalOperatorTokenScope
+  | AdminTokenScope
   | LegacyBuildTokenScope
   | ResourceTokenScope
   | OperatorTokenScope
@@ -63,7 +84,38 @@ const commonScope = {
   session: z.string().min(1),
   exp: z.number().int(),
 }
+const exactIdentity = z
+  .string()
+  .min(1)
+  .refine((value) => value !== '*')
+const delegatedClaims = z
+  .strictObject({
+    repo: exactIdentity,
+    kind: z.enum(['build-runner', 'build-phase', 'harvest-runner', 'harvest-phase']),
+    id: exactIdentity,
+    anchor: z.number().int().positive(),
+    session: exactIdentity.optional(),
+    execution: exactIdentity.optional(),
+    leaseHolder: exactIdentity.optional(),
+  })
+  .refine(
+    (claims) =>
+      claims.kind.endsWith('-phase') === (claims.session !== undefined) &&
+      claims.kind.startsWith('harvest') === (claims.execution !== undefined),
+  )
 const tokenScopeSchema = z.union([
+  z.strictObject({ version: z.literal(2), delegation: delegatedClaims }),
+  z.strictObject({
+    version: z.literal(1),
+    internalOperator: z.strictObject({ user: z.string().trim().min(1), repo: z.string().min(1) }),
+    exp: z.number().int(),
+    via: viaSchema.optional(),
+  }),
+  z.strictObject({
+    version: z.literal(1),
+    ownerAdmin: z.strictObject({ user: z.string().trim().min(1) }),
+    exp: z.number().int(),
+  }),
   z.strictObject({ build: z.string().min(1), ...commonScope }),
   z.strictObject({
     resource: z.strictObject({
@@ -85,6 +137,13 @@ export function tokenResource(scope: TokenScope): {
   kind: 'build' | 'repo' | 'session' | 'admin' | 'operator' | 'deployment'
   id: string
 } {
+  if ('delegation' in scope)
+    return {
+      kind: scope.delegation.kind.startsWith('build') ? 'build' : 'repo',
+      id: scope.delegation.kind.startsWith('build') ? scope.delegation.id : scope.delegation.repo,
+    }
+  if ('ownerAdmin' in scope) return { kind: 'admin', id: '*' }
+  if ('internalOperator' in scope) return { kind: 'operator', id: scope.internalOperator.user }
   if ('operator' in scope) {
     return scope.operator === true
       ? { kind: 'deployment', id: '*' }
@@ -108,7 +167,9 @@ export function mintToken(secret: string, scope: TokenScope): string {
 /**
  * Bad signature, malformed token, unparseable scope, or expired → null —
  * verification never explains itself to the caller (the server maps null to
- * 401). The signature compare is timing-safe via `crypto.timingSafeEqual`.
+ * 401). Version-2 grants deliberately have no fixed expiration: the service
+ * must additionally validate their registered project and durable lifecycle.
+ * The signature compare is timing-safe via `crypto.timingSafeEqual`.
  */
 export function verifyToken(secret: string, token: string, now: Date): TokenScope | null {
   const parts = token.split('.')
@@ -132,6 +193,6 @@ export function verifyToken(secret: string, token: string, now: Date): TokenScop
   }
   const scope = tokenScopeSchema.safeParse(raw)
   if (!scope.success) return null
-  if (scope.data.exp <= now.getTime()) return null
+  if ('exp' in scope.data && scope.data.exp <= now.getTime()) return null
   return scope.data
 }

package/packages/core/src/store/ticket-asset-snapshots.ts

@@ -0,0 +1,192 @@
+import { randomUUID } from 'node:crypto'
+import { gzipSync, gunzipSync } from 'node:zlib'
+import { z } from 'zod'
+import type { TicketAssetStore } from '../ports/types'
+import type { PinnedAsset } from '../events/payloads'
+import { contentHash, type BuildStore } from './types'
+import {
+  pinnedAssetOf,
+  summarizeTicketAsset,
+  validateTicketAssetInput,
+  validateTicketAssetStructure,
+  type TicketAsset,
+} from './ticket-assets'
+
+const CHUNK_BYTES = 256 * 1024
+const refSchema = z.strictObject({
+  kind: z.string().regex(/^ticket-snapshot-[a-f0-9-]+$/),
+  revision: z.number().int().nonnegative(),
+})
+const manifestSchema = z.strictObject({
+  version: z.literal(1),
+  meta: z.strictObject({
+    repo: z.string(),
+    ticketId: z.string(),
+    kind: z.string(),
+    name: z.string(),
+    revision: z.number().int().nonnegative(),
+    layout: z.enum(['file', 'tree']),
+    size: z.number().int().nonnegative(),
+    createdAt: z.string(),
+    entries: z.array(
+      z.discriminatedUnion('type', [
+        z.strictObject({ type: z.literal('dir'), path: z.string() }),
+        z.strictObject({
+          type: z.literal('file'),
+          path: z.string(),
+          size: z.number().int().nonnegative(),
+          blobRef: z.string(),
+        }),
+      ]),
+    ),
+  }),
+  files: z.array(
+    z.strictObject({
+      path: z.string(),
+      chunks: z.array(
+        refSchema.extend({ hash: z.string(), size: z.number().int().min(1).max(CHUNK_BYTES) }),
+      ),
+    }),
+  ),
+})
+
+function verifyMetadata(
+  meta: TicketAsset['meta'],
+  repo: string,
+  ticketId: string,
+  pin: PinnedAsset,
+): void {
+  const summary = pinnedAssetOf(summarizeTicketAsset(meta))
+  if (
+    meta.repo !== repo ||
+    meta.ticketId !== ticketId ||
+    Object.entries(summary).some(([key, value]) => pin[key as keyof typeof summary] !== value) ||
+    validateTicketAssetStructure(meta) !== meta.size
+  )
+    throw new Error('inconsistent ticket asset snapshot metadata')
+}
+
+function verify(asset: TicketAsset, repo: string, ticketId: string, pin: PinnedAsset): void {
+  const { meta, entries } = asset
+  verifyMetadata(meta, repo, ticketId, pin)
+  if (
+    validateTicketAssetInput({ ...meta, entries }) !== meta.size ||
+    entries.length !== meta.entries.length
+  ) {
+    throw new Error('inconsistent ticket asset snapshot metadata')
+  }
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!
+    const stored = meta.entries[i]!
+    if (
+      entry.path !== stored.path ||
+      entry.type !== stored.type ||
+      (entry.type === 'file' &&
+        stored.type === 'file' &&
+        (entry.content.length !== stored.size || contentHash(entry.content) !== stored.blobRef))
+    ) {
+      throw new Error('inconsistent ticket asset snapshot content')
+    }
+  }
+}
+
+/** Copy exact sampled revisions before publishing any pins. No current ticket rows
+ * are written to the destination; their revision sequences remain independent. */
+export async function prepareAssetSnapshots(
+  source: Pick<TicketAssetStore, 'listTicketAssets' | 'getTicketAsset'>,
+  store: Pick<BuildStore, 'putRepoArtifact' | 'ensureRepo'>,
+  repo: string,
+  ticketId: string,
+  canonicalTicketId: string = ticketId,
+): Promise<PinnedAsset[]> {
+  const pins = (await source.listTicketAssets(repo, ticketId)).map(pinnedAssetOf)
+  if (pins.length > 0) await store.ensureRepo(repo)
+  for (const pin of pins) {
+    const asset = await source.getTicketAsset(repo, ticketId, pin.kind, pin.name, pin.revision)
+    if (!asset) throw new Error('sampled ticket asset revision is missing')
+    manifestSchema.shape.meta.parse(asset.meta)
+    verify(asset, repo, canonicalTicketId, pin)
+    const files = []
+    for (const entry of asset.entries) {
+      if (entry.type !== 'file') continue
+      const chunks = []
+      for (let start = 0; start < entry.content.length; start += CHUNK_BYTES) {
+        const bytes = entry.content.slice(start, start + CHUNK_BYTES)
+        const meta = await store.putRepoArtifact(repo, {
+          kind: `ticket-snapshot-${randomUUID()}`,
+          content: bytes,
+        })
+        chunks.push({
+          kind: meta.kind,
+          revision: meta.revision,
+          size: bytes.length,
+          hash: contentHash(bytes),
+        })
+      }
+      files.push({ path: entry.path, chunks })
+    }
+    const meta = await store.putRepoArtifact(repo, {
+      kind: `ticket-snapshot-${randomUUID()}`,
+      // Compression also bounds manifests with many maximum-length escaped paths.
+      content: gzipSync(JSON.stringify({ version: 1, meta: { ...asset.meta, ticketId }, files })),
+    })
+    pin.snapshot = { kind: meta.kind, revision: meta.revision }
+  }
+  return pins
+}
+
+export async function readAssetSnapshot(
+  store: Pick<BuildStore, 'getRepoArtifact'>,
+  repo: string,
+  ticketId: string,
+  pin: PinnedAsset,
+  historicalTicketId?: string,
+): Promise<TicketAsset> {
+  if (!pin.snapshot) throw new Error('missing snapshot reference')
+  const artifact = await store.getRepoArtifact(repo, pin.snapshot.kind, pin.snapshot.revision)
+  if (!artifact) throw new Error('ticket asset snapshot manifest is missing')
+  const manifest = manifestSchema.parse(
+    JSON.parse(gunzipSync(artifact.content, { maxOutputLength: 4 * 1024 * 1024 }).toString('utf8')),
+  )
+  // BuildStore projections can display a readable ID while the immutable
+  // build.created event and its older snapshots retain the storage alias.
+  const snapshotTicketId =
+    manifest.meta.ticketId === historicalTicketId ? historicalTicketId : ticketId
+  verifyMetadata(manifest.meta, repo, snapshotTicketId, pin)
+  const entries: TicketAsset['entries'] = []
+  const files = new Map(manifest.files.map((file) => [file.path, file]))
+  if (
+    files.size !== manifest.files.length ||
+    files.size !== manifest.meta.entries.filter((entry) => entry.type === 'file').length
+  ) {
+    throw new Error('inconsistent ticket asset snapshot files')
+  }
+  for (const entry of manifest.meta.entries) {
+    if (entry.type === 'dir') {
+      entries.push(entry)
+      continue
+    }
+    const file = files.get(entry.path)
+    if (!file || file.chunks.reduce((size, chunk) => size + chunk.size, 0) !== entry.size) {
+      throw new Error('inconsistent ticket asset snapshot chunks')
+    }
+    const content = new Uint8Array(entry.size)
+    let offset = 0
+    for (const chunk of file.chunks) {
+      const artifact = await store.getRepoArtifact(repo, chunk.kind, chunk.revision)
+      if (
+        !artifact ||
+        artifact.content.length !== chunk.size ||
+        contentHash(artifact.content) !== chunk.hash
+      ) {
+        throw new Error('ticket asset snapshot chunk is missing or corrupt')
+      }
+      content.set(artifact.content, offset)
+      offset += chunk.size
+    }
+    entries.push({ type: 'file', path: entry.path, content })
+  }
+  const asset = { meta: manifest.meta, entries }
+  verify(asset, repo, snapshotTicketId, pin)
+  return asset
+}