main
ply4 git calls26 ms49 KiB3 cachedprotocol v2
857 lines32 KiBRaw
1import { AsyncLocalStorage } from 'node:async_hooks'
2import { createHash } from 'node:crypto'
3import { appendFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
4import { dirname, join, relative } from 'node:path'
5import { promisify } from 'node:util'
6import { gzip } from 'node:zlib'
7import { asRecord } from './json.ts'
8import { RUN_ID } from './run-dir.ts'
9import { redact } from './redact.ts'
10import { isGitSha, type ReleasePair } from './release.ts'
11import type { Fault } from './result.ts'
12import { isSecret, type Secret } from './secret.ts'
13import type { CommandNote } from './trace.ts'
15const observationBrand = Symbol('observation')
17/** Returned only by `RunLog.observation`. A decision cannot be built from anything else. */
18export type ObservationRef = {
19 readonly seq: number
20 readonly [observationBrand]: 'observation'
23export type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json }
25export type DecisionOutcome = 'advance' | 'hold' | 'insufficient_data' | 'insufficient_samples' | 'rollback' | 'stop' | 'harness_fault' | 'harness_unhealthy' | 'state_conflict' | 'cleanup_leak'
27export type RuleRef = {
28 readonly name: string
29 readonly value: number | string
32export type StageTiming = {
33 readonly name: string
34 readonly startedAt: string
35 readonly finishedAt: string
36 readonly durationMs: number
39export type StepBurn = {
40 readonly percent: number
41 readonly burns: { readonly [slo: string]: number | null }
44type Base = {
45 readonly seq: number
46 readonly ts: string
47 readonly run_id: string
48 readonly stage: string
51export type LifecycleStarted = {
52 readonly event: 'run_started'
53 readonly config: Json
54 readonly tools: { readonly node: string; readonly cf: string; readonly git: string }
55 readonly plySha: string | null
56 readonly plyWebSha: string
57 readonly host: string
58 /** The release this run is shipping. Null on a command that does not deploy. */
59 readonly release: ReleasePair | null
62export type LifecycleFinished = {
63 readonly event: 'run_finished'
64 readonly verdict: 'pass' | 'fail'
65 readonly reason: string | null
66 readonly rolledBack: boolean
67 readonly rollbackReason: string | null
68 readonly versionId: string | null
69 readonly plySha: string | null
70 readonly plyMergedAt: string | null
71 readonly plyWebSha: string
72 readonly release: ReleasePair | null
73 readonly smoke: { readonly passed: number; readonly failed: number }
74 readonly stages: readonly StageTiming[]
75 readonly steps: readonly StepBurn[]
76 readonly liveAt: string | null
77 readonly failedAt: string | null
78 readonly restoredAt: string | null
79 /** Null on a pass. `harness_fault` is a script, query, or join error and is not a change failure. */
80 readonly fault: Fault | null
83/** Appended when `--sha` continues an unfinished run. The run id stays the one on this log. */
84export type LifecycleResumed = {
85 readonly event: 'resumed'
86 readonly sha: string
87 readonly release: ReleasePair | null
90export type CdEvent =
91 | (Base & { readonly kind: 'lifecycle'; readonly payload: LifecycleStarted | LifecycleFinished | LifecycleResumed })
92 | (Base & {
93 readonly kind: 'command'
94 readonly payload: {
95 readonly argv: readonly string[]
96 readonly cwd: string
97 readonly exitCode: number
98 readonly durationMs: number
99 readonly stdoutDigest: string
100 readonly stderrDigest: string
101 readonly stdoutPath: string
102 readonly stderrPath: string
103 }
104 })
105 | (Base & {
106 readonly kind: 'observation'
107 readonly payload: {
108 readonly measurement: Json
109 readonly query: Json
110 readonly window: { readonly from: string; readonly to: string }
111 readonly responsePath: string
112 }
113 })
114 | (Base & {
115 readonly kind: 'decision'
116 readonly payload: {
117 readonly inputs: readonly number[]
118 readonly rules: readonly RuleRef[]
119 readonly outcome: DecisionOutcome
120 readonly reason: string
121 }
122 })
123 | (Base & {
124 readonly kind: 'state_change'
125 readonly payload: {
126 readonly before: readonly { readonly versionId: string; readonly percentage: number }[]
127 readonly after: readonly { readonly versionId: string; readonly percentage: number }[]
128 readonly deploymentId: string | null
129 }
130 })
131 | (Base & {
132 readonly kind: 'request'
133 readonly payload: {
134 readonly method: string
135 readonly url: string
136 readonly status: number
137 readonly version: string | null
138 readonly latencyMs: number
139 readonly cfRay: string | null
140 readonly requestId: string | null
141 readonly artifactsRay: string | null
142 }
143 })
144 | (Base & { readonly kind: 'error'; readonly payload: { readonly message: string; readonly context: Json } })
145 | (Base & { readonly kind: 'annotation'; readonly payload: { readonly note: 'false_positive'; readonly reason: string } })
146 | (Base & { readonly kind: 'policy'; readonly payload: { readonly sha256: string; readonly path: string; readonly body: Json; readonly release: ReleasePair | null } })
148export type RunFacts = {
149 versionId: string | null
150 plySha: string | null
151 plyMergedAt: string | null
152 plyWebSha: string
153 release: ReleasePair | null
154 rolledBack: boolean
155 rollbackReason: string | null
156 smokePassed: number
157 smokeFailed: number
158 stages: StageTiming[]
159 steps: StepBurn[]
160 liveAt: string | null
161 failedAt: string | null
162 restoredAt: string | null
163 fault: Fault | null
166const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/
167const OUTCOMES = new Set<DecisionOutcome>(['advance', 'hold', 'insufficient_data', 'insufficient_samples', 'rollback', 'stop', 'harness_fault', 'harness_unhealthy', 'state_conflict', 'cleanup_leak'])
168const FAULTS = new Set<Fault>(['worker', 'harness_fault', 'state_conflict', 'insufficient_samples', 'harness_unhealthy'])
170export function isoOffset(date: Date): string {
171 const pad = (value: number, width = 2) => String(Math.trunc(Math.abs(value))).padStart(width, '0')
172 const offset = -date.getTimezoneOffset()
173 const sign = offset >= 0 ? '+' : '-'
174 return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}${sign}${pad(Math.trunc(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`
177const gzipAsync = promisify(gzip)
179/** A Node fs error with this `code`. */
180export function hasCode(error: unknown, code: string): boolean {
181 return typeof error === 'object' && error !== null && 'code' in error && (error as { readonly code: unknown }).code === code
184/**
185 * Bulky bytes (command stdout and stderr, observation bodies) are stored once each, gzipped, at `blobs/<sha256>.gz`.
186 * A run that passes without a rollback deletes `blobs/` before it seals: the gates read only `measurement`, which
187 * is in events.jsonl. A failed or rolled-back run keeps them. Before 2026-11-07 every poll wrote a plain
188 * captures/<seq>.stdout and a raw/<seq>.json copy of the same pages, 100-400 MB per run.
189 */
190export const BLOB_DIR = 'blobs'
192function sha256(text: string): string {
193 return createHash('sha256').update(text).digest('hex')
196function freezeJson(value: unknown, path: string): Json {
197 if (isSecret(value)) throw new Error(`Secret at ${path} cannot be recorded`)
198 if (value === null) return null
199 if (typeof value === 'string' || typeof value === 'boolean') return value
200 if (typeof value === 'number') {
201 if (!Number.isFinite(value)) throw new Error(`non-finite number at ${path}`)
202 return value
203 }
204 if (Array.isArray(value)) return value.map((item, index) => freezeJson(item, `${path}[${index}]`))
205 if (typeof value === 'object') {
206 const out: { [key: string]: Json } = {}
207 for (const [key, item] of Object.entries(value)) {
208 if (item === undefined) continue
209 out[key] = freezeJson(item, `${path}.${key}`)
210 }
211 return out
212 }
213 throw new Error(`value at ${path} is not JSON`)
216function needRecord(value: unknown, what: string): Record<string, unknown> {
217 const rec = asRecord(value)
218 if (!rec) throw new Error(`${what} is not an object`)
219 return rec
222function needString(rec: Record<string, unknown>, key: string): string {
223 const value = rec[key]
224 if (typeof value !== 'string') throw new Error(`${key} is not a string`)
225 return value
228function needNumber(rec: Record<string, unknown>, key: string): number {
229 const value = rec[key]
230 if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(`${key} is not a number`)
231 return value
234function needBoolean(rec: Record<string, unknown>, key: string): boolean {
235 const value = rec[key]
236 if (typeof value !== 'boolean') throw new Error(`${key} is not a boolean`)
237 return value
240function jsonValue(value: unknown, path: string): Json {
241 return freezeJson(value, path)
244function stringOrNull(value: unknown, key: string): string | null {
245 if (value === null) return null
246 if (typeof value !== 'string') throw new Error(`${key} is not a string`)
247 return value
250function shares(value: unknown, key: string): { versionId: string; percentage: number }[] {
251 if (!Array.isArray(value)) throw new Error(`${key} is not a list`)
252 return value.map((item, index) => {
253 const rec = needRecord(item, `${key}[${index}]`)
254 return { versionId: needString(rec, 'versionId'), percentage: needNumber(rec, 'percentage') }
255 })
258function rules(value: unknown): RuleRef[] {
259 if (!Array.isArray(value) || value.length === 0) throw new Error('a decision needs a rule')
260 return value.map((item, index) => {
261 const rec = needRecord(item, `rules[${index}]`)
262 const ruleValue = rec.value
263 if (typeof ruleValue !== 'number' && typeof ruleValue !== 'string') throw new Error('rule value is not a number or string')
264 if (typeof ruleValue === 'number' && !Number.isFinite(ruleValue)) throw new Error('rule value is not finite')
265 return { name: needString(rec, 'name'), value: ruleValue }
266 })
269function parseFault(value: unknown): Fault | null {
270 if (value === undefined || value === null) return null
271 if (typeof value === 'string' && FAULTS.has(value as Fault)) return value as Fault
272 throw new Error('fault is not a known kind')
275function parseRelease(value: unknown): ReleasePair | null {
276 if (value === undefined || value === null) return null
277 const rec = asRecord(value)
278 if (!rec) throw new Error('release is not a pair')
279 const ply = needString(rec, 'ply')
280 const web = needString(rec, 'web')
281 if (!isGitSha(ply) || !isGitSha(web)) throw new Error('release shas must be 40 hex')
282 return { ply, web }
285function parseLifecycle(payload: Record<string, unknown>): LifecycleStarted | LifecycleFinished | LifecycleResumed {
286 const event = needString(payload, 'event')
287 if (event === 'run_started') {
288 const tools = needRecord(payload.tools, 'tools')
289 return {
290 event,
291 config: jsonValue(payload.config, 'config'),
292 tools: { node: needString(tools, 'node'), cf: needString(tools, 'cf'), git: needString(tools, 'git') },
293 plySha: stringOrNull(payload.plySha, 'plySha'),
294 plyWebSha: needString(payload, 'plyWebSha'),
295 host: needString(payload, 'host'),
296 release: parseRelease(payload.release),
297 }
298 }
299 if (event === 'resumed') return { event, sha: needString(payload, 'sha'), release: parseRelease(payload.release) }
300 if (event === 'run_finished') {
301 const smoke = needRecord(payload.smoke, 'smoke')
302 if (!Array.isArray(payload.stages) || !Array.isArray(payload.steps)) throw new Error('run_finished needs stages and steps')
303 return {
304 event,
305 verdict: payload.verdict === 'pass' || payload.verdict === 'fail' ? payload.verdict : (() => { throw new Error('verdict is not pass or fail') })(),
306 reason: stringOrNull(payload.reason, 'reason'),
307 rolledBack: needBoolean(payload, 'rolledBack'),
308 rollbackReason: stringOrNull(payload.rollbackReason, 'rollbackReason'),
309 versionId: stringOrNull(payload.versionId, 'versionId'),
310 plySha: stringOrNull(payload.plySha, 'plySha'),
311 plyMergedAt: stringOrNull(payload.plyMergedAt, 'plyMergedAt'),
312 plyWebSha: needString(payload, 'plyWebSha'),
313 release: parseRelease(payload.release),
314 smoke: { passed: needNumber(smoke, 'passed'), failed: needNumber(smoke, 'failed') },
315 stages: payload.stages.map((item, index) => {
316 const rec = needRecord(item, `stages[${index}]`)
317 return {
318 name: needString(rec, 'name'),
319 startedAt: needString(rec, 'startedAt'),
320 finishedAt: needString(rec, 'finishedAt'),
321 durationMs: needNumber(rec, 'durationMs'),
322 }
323 }),
324 steps: payload.steps.map((item, index) => {
325 const rec = needRecord(item, `steps[${index}]`)
326 const burns = needRecord(rec.burns, 'burns')
327 const mapped: { [slo: string]: number | null } = {}
328 for (const [key, burn] of Object.entries(burns)) {
329 if (burn !== null && (typeof burn !== 'number' || !Number.isFinite(burn))) throw new Error(`burn ${key} is not a number`)
330 mapped[key] = burn === null ? null : burn
331 }
332 return { percent: needNumber(rec, 'percent'), burns: mapped }
333 }),
334 liveAt: stringOrNull(payload.liveAt, 'liveAt'),
335 failedAt: stringOrNull(payload.failedAt, 'failedAt'),
336 restoredAt: stringOrNull(payload.restoredAt, 'restoredAt'),
337 fault: parseFault(payload.fault),
338 }
339 }
340 throw new Error(`unknown lifecycle event ${event}`)
343function parsePayload(kind: CdEvent['kind'], payload: unknown): CdEvent['payload'] {
344 const rec = needRecord(payload, kind)
345 if (kind === 'lifecycle') return parseLifecycle(rec)
346 if (kind === 'command') {
347 if (!Array.isArray(rec.argv) || rec.argv.some(part => typeof part !== 'string')) throw new Error('argv is not a list of strings')
348 return {
349 argv: rec.argv,
350 cwd: needString(rec, 'cwd'),
351 exitCode: needNumber(rec, 'exitCode'),
352 durationMs: needNumber(rec, 'durationMs'),
353 stdoutDigest: needString(rec, 'stdoutDigest'),
354 stderrDigest: needString(rec, 'stderrDigest'),
355 stdoutPath: needString(rec, 'stdoutPath'),
356 stderrPath: needString(rec, 'stderrPath'),
357 }
358 }
359 if (kind === 'observation') {
360 const window = needRecord(rec.window, 'window')
361 return {
362 measurement: jsonValue(rec.measurement, 'measurement'),
363 query: jsonValue(rec.query, 'query'),
364 window: { from: needString(window, 'from'), to: needString(window, 'to') },
365 responsePath: needString(rec, 'responsePath'),
366 }
367 }
368 if (kind === 'decision') {
369 if (!Array.isArray(rec.inputs) || rec.inputs.length === 0 || rec.inputs.some(item => typeof item !== 'number')) {
370 throw new Error('a decision needs an observation')
371 }
372 const outcome = needString(rec, 'outcome')
373 if (!OUTCOMES.has(outcome as DecisionOutcome)) throw new Error(`unknown decision outcome ${outcome}`)
374 return { inputs: rec.inputs, rules: rules(rec.rules), outcome: outcome as DecisionOutcome, reason: needString(rec, 'reason') }
375 }
376 if (kind === 'state_change') {
377 return {
378 before: shares(rec.before, 'before'),
379 after: shares(rec.after, 'after'),
380 deploymentId: stringOrNull(rec.deploymentId, 'deploymentId'),
381 }
382 }
383 if (kind === 'request') {
384 return {
385 method: needString(rec, 'method'),
386 url: needString(rec, 'url'),
387 status: needNumber(rec, 'status'),
388 version: stringOrNull(rec.version, 'version'),
389 latencyMs: needNumber(rec, 'latencyMs'),
390 cfRay: stringOrNull(rec.cfRay, 'cfRay'),
391 requestId: stringOrNull(rec.requestId, 'requestId'),
392 artifactsRay: stringOrNull(rec.artifactsRay, 'artifactsRay'),
393 }
394 }
395 if (kind === 'annotation') {
396 const note = needString(rec, 'note')
397 if (note !== 'false_positive') throw new Error(`unknown annotation ${note}`)
398 const reason = needString(rec, 'reason')
399 if (!reason.trim()) throw new Error('annotation reason is empty')
400 return { note: 'false_positive', reason }
401 }
402 if (kind === 'policy') {
403 const sha256 = needString(rec, 'sha256')
404 if (!/^[0-9a-f]{64}$/.test(sha256)) throw new Error('policy sha256 is not 64 hex')
405 return { sha256, path: needString(rec, 'path'), body: jsonValue(rec.body, 'body'), release: parseRelease(rec.release) }
406 }
407 return { message: needString(rec, 'message'), context: jsonValue(rec.context, 'context') }
410/** One event object. Throws when the shape is not the log ADT. */
411export function parseEvent(value: unknown): CdEvent {
412 const rec = needRecord(value, 'event')
413 const kind = needString(rec, 'kind')
414 const known = ['lifecycle', 'command', 'observation', 'decision', 'state_change', 'request', 'error', 'annotation', 'policy']
415 if (!known.includes(kind)) throw new Error(`unknown event kind ${kind}`)
416 const ts = needString(rec, 'ts')
417 if (!ISO.test(ts)) throw new Error('ts is not an ISO timestamp with a numeric offset')
418 const event = {
419 seq: needNumber(rec, 'seq'),
420 ts,
421 run_id: needString(rec, 'run_id'),
422 stage: needString(rec, 'stage'),
423 kind,
424 payload: parsePayload(kind as CdEvent['kind'], rec.payload),
425 }
426 return event as CdEvent
429/**
430 * Append a false-positive note for a past run. The line is added to the ledger.
431 * Earlier lines are not rewritten, and the sealed run directory is not opened.
432 */
433export async function appendFalsePositive(ledgerPath: string, runId: string, reason: string, now = new Date()): Promise<CdEvent> {
434 if (!RUN_ID.test(runId)) throw new Error('run id must look like 2026-11-01T00-10-02-620Z')
435 const trimmed = reason.trim()
436 if (!trimmed || /[\n\r]/.test(reason)) throw new Error('false-positive reason must be one line')
437 let seq = 1
438 try {
439 const text = await readFile(ledgerPath, 'utf8')
440 for (const line of text.split('\n')) {
441 if (!line.trim()) continue
442 try {
443 const event = parseEvent(JSON.parse(line) as unknown)
444 if (event.run_id === runId && event.seq >= seq) seq = event.seq + 1
445 } catch {
446 // A bad ledger line stays where it is. The annotation is still appended.
447 }
448 }
449 } catch (error) {
450 const code = error && typeof error === 'object' && 'code' in error ? (error as { code?: unknown }).code : undefined
451 if (code !== 'ENOENT') throw error
452 }
453 const event: CdEvent = {
454 seq,
455 ts: isoOffset(now),
456 run_id: runId,
457 stage: 'run',
458 kind: 'annotation',
459 payload: { note: 'false_positive', reason: trimmed },
460 }
461 await mkdir(dirname(ledgerPath), { recursive: true })
462 await appendFile(ledgerPath, JSON.stringify(event) + '\n')
463 return event
466/** Seq starts at 1 and each decision cites an earlier observation in this run. */
467export function validateRun(events: readonly CdEvent[]): void {
468 let expected = 1
469 let runId = ''
470 const observations = new Set<number>()
471 for (const event of events) {
472 if (event.seq !== expected) throw new Error(`expected seq ${expected}, saw ${event.seq}`)
473 expected += 1
474 if (!runId) runId = event.run_id
475 if (event.run_id !== runId) throw new Error('run log has two run ids')
476 if (event.kind === 'observation') observations.add(event.seq)
477 if (event.kind === 'decision') {
478 for (const input of event.payload.inputs) {
479 if (!observations.has(input) || input >= event.seq) {
480 throw new Error(`decision ${event.seq} cites ${input}, which is not an earlier observation`)
481 }
482 }
483 }
484 }
487export async function readEvents(dir: string): Promise<CdEvent[]> {
488 const text = await readFile(join(dir, 'events.jsonl'), 'utf8')
489 const events: CdEvent[] = []
490 for (const line of text.split('\n')) {
491 if (!line.trim()) continue
492 events.push(parseEvent(JSON.parse(line) as unknown))
493 }
494 validateRun(events)
495 return events
498function isObservationRef(value: unknown): value is ObservationRef {
499 return typeof value === 'object' && value !== null && (value as { [observationBrand]?: unknown })[observationBrand] === 'observation'
502function scrub(text: string, secrets: readonly string[]): string {
503 return redact(text, secrets)
506async function filesIn(dir: string, root = dir): Promise<string[]> {
507 const entries = await readdir(dir, { withFileTypes: true })
508 const out: string[] = []
509 for (const entry of entries) {
510 const path = join(dir, entry.name)
511 if (entry.isDirectory()) out.push(...await filesIn(path, root))
512 else if (entry.isFile() && entry.name !== 'manifest.json') out.push(relative(root, path))
513 }
514 return out.sort()
517export class RunLog {
518 readonly #dir: string
519 readonly #ledger: string
520 readonly #runId: string
521 readonly #concealed: string[] = []
522 #stage = 'run'
523 #seq = 1
524 #tail: Promise<void> = Promise.resolve()
525 #events: CdEvent[] = []
526 #started = false
527 #finished = false
528 #sealed = false
529 #verdict: 'pass' | 'fail' | null = null
530 readonly facts: RunFacts = {
531 versionId: null,
532 plySha: null,
533 plyMergedAt: null,
534 plyWebSha: 'unknown',
535 release: null,
536 rolledBack: false,
537 rollbackReason: null,
538 smokePassed: 0,
539 smokeFailed: 0,
540 stages: [],
541 steps: [],
542 liveAt: null,
543 failedAt: null,
544 restoredAt: null,
545 fault: null,
546 }
548 private constructor(dir: string, ledger: string, runId: string) {
549 this.#dir = dir
550 this.#ledger = ledger
551 this.#runId = runId
552 }
554 static async open(dir: string, ledger: string, runId: string): Promise<RunLog> {
555 await mkdir(dir, { recursive: true })
556 return new RunLog(dir, ledger, runId)
557 }
559 /** Continue an unfinished run. Seq follows the last event. A sealed log is not reopened here. */
560 static async reopen(dir: string, ledger: string): Promise<RunLog> {
561 const events = await readEvents(dir)
562 const first = events[0]
563 if (!first) throw new Error('run has no events')
564 const log = new RunLog(dir, ledger, first.run_id)
565 log.#events = events.slice()
566 log.#seq = (events[events.length - 1]?.seq ?? 0) + 1
567 log.#started = events.some(event => event.kind === 'lifecycle' && event.payload.event === 'run_started')
568 log.#finished = events.some(event => event.kind === 'lifecycle' && event.payload.event === 'run_finished')
569 const started = events.find(event => event.kind === 'lifecycle' && event.payload.event === 'run_started')
570 if (started && started.kind === 'lifecycle' && started.payload.event === 'run_started') {
571 log.facts.plySha = started.payload.plySha
572 log.facts.plyWebSha = started.payload.plyWebSha
573 log.facts.release = started.payload.release
574 }
575 return log
576 }
578 get runId(): string {
579 return this.#runId
580 }
582 get dir(): string {
583 return this.#dir
584 }
586 get finished(): boolean {
587 return this.#finished
588 }
590 get sealed(): boolean {
591 return this.#sealed
592 }
594 recorded(): readonly CdEvent[] {
595 return this.#events
596 }
598 /** Remember a credential so a later line cannot contain it. The value is not written. */
599 conceal(value: string): void {
600 if (value.length >= 8) this.#concealed.push(value)
601 }
603 concealSecret(secret: Secret): void {
604 this.conceal(secret.reveal())
605 }
607 useStage(stage: string): void {
608 this.#stage = stage
609 }
611 patch(partial: Partial<RunFacts>): void {
612 Object.assign(this.facts, partial)
613 }
615 addStage(timing: StageTiming): void {
616 this.facts.stages.push(timing)
617 }
619 addStep(step: StepBurn): void {
620 this.facts.steps.push(step)
621 }
623 addSmoke(passed: number, failed: number): void {
624 this.facts.smokePassed += passed
625 this.facts.smokeFailed += failed
626 }
628 async resumed(sha: string, release: ReleasePair | null = null): Promise<void> {
629 await this.#enqueue(async () => {
630 await this.#append('lifecycle', { event: 'resumed', sha, release }, 'run')
631 })
632 }
634 async recordPolicy(input: { readonly sha256: string; readonly path: string; readonly body: Json; readonly release?: ReleasePair | null }): Promise<void> {
635 await this.#enqueue(async () => {
636 await this.#append('policy', { sha256: input.sha256, path: input.path, body: input.body, release: input.release ?? null }, 'run')
637 })
638 }
640 async started(input: Omit<LifecycleStarted, 'event' | 'release'> & { readonly release?: ReleasePair | null }): Promise<void> {
641 await this.#enqueue(async () => {
642 if (this.#started) throw new Error('run already started')
643 this.#started = true
644 this.facts.plySha = input.plySha
645 this.facts.plyWebSha = input.plyWebSha
646 this.facts.release = input.release ?? null
647 await this.#append('lifecycle', { event: 'run_started', ...input, release: input.release ?? null }, 'run')
648 })
649 }
651 async finish(code: number, reason: string | null): Promise<void> {
652 await this.#enqueue(async () => {
653 if (this.#finished) return
654 this.#finished = true
655 this.#verdict = code === 0 ? 'pass' : 'fail'
656 const payload: LifecycleFinished = {
657 event: 'run_finished',
658 verdict: code === 0 ? 'pass' : 'fail',
659 reason,
660 rolledBack: this.facts.rolledBack,
661 rollbackReason: this.facts.rollbackReason,
662 versionId: this.facts.versionId,
663 plySha: this.facts.plySha,
664 plyMergedAt: this.facts.plyMergedAt,
665 plyWebSha: this.facts.plyWebSha,
666 release: this.facts.release,
667 smoke: { passed: this.facts.smokePassed, failed: this.facts.smokeFailed },
668 stages: this.facts.stages,
669 steps: this.facts.steps,
670 liveAt: this.facts.liveAt,
671 failedAt: this.facts.failedAt,
672 restoredAt: this.facts.restoredAt,
673 fault: this.facts.fault,
674 }
675 await this.#append('lifecycle', payload, 'run')
676 })
677 }
679 /** True when this run's blobs are kept at seal: it failed or rolled back. */
680 get keepsBlobs(): boolean {
681 return this.#verdict !== 'pass' || this.facts.rolledBack
682 }
684 /** sha256 of `text` as a capture of it is stored: after redaction. Matches `stdoutDigest` and the blob name. */
685 digest(text: string): string {
686 return sha256(scrub(text, this.#concealed))
687 }
689 /** Drop the blobs of a clean pass, hash every file except the manifest, then refuse further writes. */
690 async seal(): Promise<void> {
691 await this.#enqueue(async () => {
692 if (!this.#finished) throw new Error('seal requires run_finished')
693 if (this.#sealed) return
694 const blobs = this.keepsBlobs ? 'kept' : 'dropped'
695 if (blobs === 'dropped') await rm(join(this.#dir, BLOB_DIR), { recursive: true, force: true })
696 const files = await filesIn(this.#dir)
697 const listed: { [path: string]: string } = {}
698 for (const file of files) {
699 const bytes = await readFile(join(this.#dir, file))
700 listed[file] = createHash('sha256').update(bytes).digest('hex')
701 }
702 const manifest = { run_id: this.#runId, sealed_at: isoOffset(new Date()), blobs, files: listed }
703 await writeFile(join(this.#dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
704 this.#sealed = true
705 })
706 }
708 async noteCommand(note: CommandNote): Promise<void> {
709 await this.#enqueue(async () => {
710 for (const part of note.argv) if (isSecret(part)) this.conceal(part.reveal())
711 const argv = note.argv.map(part => (isSecret(part) ? '<redacted>' : part))
712 const stdout = scrub(note.stdout, this.#concealed)
713 const stderr = scrub(note.stderr, this.#concealed)
714 const out = await this.#blob(stdout)
715 const err = await this.#blob(stderr)
716 await this.#append('command', {
717 argv,
718 cwd: note.cwd,
719 exitCode: note.exitCode,
720 durationMs: note.durationMs,
721 stdoutDigest: out.digest,
722 stderrDigest: err.digest,
723 stdoutPath: out.path,
724 stderrPath: err.path,
725 })
726 })
727 }
729 async observation(input: {
730 readonly measurement: unknown
731 readonly query: unknown
732 readonly from: number
733 readonly to: number
734 readonly raw: string
735 }): Promise<ObservationRef> {
736 return this.#enqueue(async () => {
737 const seq = this.#seq
738 const { path: responsePath } = await this.#blob(scrub(input.raw, this.#concealed))
739 await this.#append('observation', {
740 measurement: input.measurement,
741 query: input.query,
742 window: { from: isoOffset(new Date(input.from)), to: isoOffset(new Date(input.to)) },
743 responsePath,
744 })
745 const ref: ObservationRef = { seq, [observationBrand]: 'observation' }
746 return ref
747 })
748 }
750 async decision(input: {
751 readonly inputs: readonly [ObservationRef, ...ObservationRef[]]
752 readonly rules: readonly [RuleRef, ...RuleRef[]]
753 readonly outcome: DecisionOutcome
754 readonly reason: string
755 }): Promise<void> {
756 await this.#enqueue(async () => {
757 if (input.inputs.length === 0) throw new Error('a decision needs an observation')
758 const seqs: number[] = []
759 for (const ref of input.inputs) {
760 if (!isObservationRef(ref)) throw new Error('a decision input must be an observation')
761 const prior = this.#events.find(event => event.seq === ref.seq)
762 if (!prior || prior.kind !== 'observation') throw new Error(`decision input ${ref.seq} is not an observation`)
763 seqs.push(ref.seq)
764 }
765 if (input.rules.length === 0) throw new Error('a decision needs a rule')
766 await this.#append('decision', {
767 inputs: seqs,
768 rules: input.rules,
769 outcome: input.outcome,
770 reason: input.reason,
771 })
772 })
773 }
775 async stateChange(input: {
776 readonly before: readonly { readonly versionId: string; readonly percentage: number }[]
777 readonly after: readonly { readonly versionId: string; readonly percentage: number }[]
778 readonly deploymentId: string | null
779 }): Promise<void> {
780 await this.#enqueue(async () => {
781 await this.#append('state_change', input)
782 })
783 }
785 async request(input: {
786 readonly method: string
787 readonly url: string
788 readonly status: number
789 readonly version: string | null
790 readonly latencyMs: number
791 readonly cfRay: string | null
792 readonly requestId: string | null
793 readonly artifactsRay: string | null
794 }, stage: string = this.#stage): Promise<void> {
795 // `stage` names who sent it when that is not the stage open now: the ramp's probes run through the 100% step's dwell
796 // beside the live smoke, and were labelled smoke-live by the open stage (run 2026-11-10T14-56-52-021Z: 2,001 probes)
797 await this.#enqueue(async () => {
798 await this.#append('request', input, stage)
799 })
800 }
802 async error(message: string, context: unknown): Promise<void> {
803 await this.#enqueue(async () => {
804 await this.#append('error', { message, context })
805 })
806 }
808 /** Store already-redacted `text` once by content. A second write of the same bytes is a no-op. */
809 async #blob(text: string): Promise<{ readonly digest: string; readonly path: string }> {
810 const digest = sha256(text)
811 const path = `${BLOB_DIR}/${digest}.gz`
812 await mkdir(join(this.#dir, BLOB_DIR), { recursive: true })
813 try {
814 await writeFile(join(this.#dir, path), await gzipAsync(text), { flag: 'wx' })
815 } catch (error) {
816 if (!hasCode(error, 'EEXIST')) throw error
817 }
818 return { digest, path }
819 }
821 #enqueue<T>(job: () => Promise<T>): Promise<T> {
822 if (this.#sealed) return Promise.reject(new Error('run log is sealed'))
823 const run = this.#tail.then(job, job)
824 this.#tail = run.then(() => undefined, () => undefined)
825 return run
826 }
828 async #append(kind: CdEvent['kind'], payload: unknown, stage = this.#stage): Promise<void> {
829 if (this.#sealed) throw new Error('run log is sealed')
830 const event = {
831 seq: this.#seq,
832 ts: isoOffset(new Date()),
833 run_id: this.#runId,
834 stage,
835 kind,
836 payload: freezeJson(payload, kind),
837 }
838 this.#seq += 1
839 const line = scrub(JSON.stringify(event), this.#concealed)
840 const parsed = parseEvent(JSON.parse(line) as unknown)
841 await appendFile(join(this.#dir, 'events.jsonl'), line + '\n')
842 await mkdir(dirname(this.#ledger), { recursive: true })
843 await appendFile(this.#ledger, line + '\n')
844 this.#events.push(parsed)
845 }
848const runs = new AsyncLocalStorage<RunLog>()
850/** Stages record into the log that `fn` sees. A test that does not open a run records nothing. */
851export function withRun<T>(log: RunLog, fn: () => Promise<T>): Promise<T> {
852 return runs.run(log, fn)
855export function activeLog(): RunLog | undefined {
856 return runs.getStore()
Diagnostics4 git calls · 26 ms
CallStatusSizeTime026 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020040 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=41349
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=526b305930b8ef382f2d7a1f9c0238730a585921
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=41349
git.pkt.payload.max=41254
git.sideband.band1.bytes=41253
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=41253
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c
git.pack.full=61
Open pack map
fetch2008.3 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=18
git.response.bytes=8520
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=635ecfd136c5f3deeb3feb77b49e6d360e791ec7
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=8520
git.pkt.payload.max=8499
git.sideband.band1.bytes=8498
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
Ref
refs/heads/main
Commit
526b305930b8ef382f2d7a1f9c0238730a585921
cf-ray
a5e2bb884b94cfc3
Request
f2e0524e…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format