@downtrace/protocol 0.6.0 → 0.7.1

package/dist/index.js

@@ -23,7 +23,8 @@ var aggregates_schema_default = {
 				"0.3.0",
 				"0.4.0",
 				"0.5.0",
-				"0.6.0"
+				"0.6.0",
+				"0.7.0"
 			],
 			"description": "Protocol version this batch conforms to. Every published minor of v0 stays acceptable."
 		},
@@ -32,11 +33,30 @@ var aggregates_schema_default = {
 		"deploy": { "$ref": "#/$defs/DeployInfo" },
 		"intervals": {
 			"type": "array",
-			"minItems": 1,
+			"minItems": 0,
 			"maxItems": 6,
-			"items": { "$ref": "#/$defs/Interval" }
+			"items": { "$ref": "#/$defs/Interval" },
+			"description": "The intervals this batch carries. May be empty when the batch carries a profile: the profile has a cadence of its own and hangs off the batch, not off an interval (ADR 0017), so tying its delivery to one meant it was lost whenever a window closed with no traffic — at shutdown, always (gh-375). A batch with neither is refused by the cloud with a reason, which the schema cannot say without making the generated types unusable."
 		},
-		"profile": { "$ref": "#/$defs/Profile" }
+		"profile": { "$ref": "#/$defs/Profile" },
+		"captures": {
+			"type": "array",
+			"maxItems": 16,
+			"items": { "$ref": "#/$defs/CaptureProgress" },
+			"description": "Progress on the captures this sender was asked for. Absent from every sender that predates it, and from every batch with nothing to report. Bounded like the answer that carries the orders."
+		},
+		"exceptions": {
+			"type": "array",
+			"maxItems": 32,
+			"items": { "$ref": "#/$defs/ProcessException" },
+			"description": "Distinct exception signatures this process saw outside any request. Absent from every sender that predates it and from every batch with none. Bounded: a process crashing in a loop must not become an unbounded batch."
+		},
+		"triggers": {
+			"type": "array",
+			"maxItems": 4,
+			"items": { "$ref": "#/$defs/LocalTrigger" },
+			"description": "Local signals that ask for a capture. `product.md:124` gives the instrumentation «disparar por señales locales»: it sees a process in trouble before any aggregate crosses the cloud, and asking in the batch costs no channel of its own — the answer already carries the orders (ADR 0071). Absent from every sender that predates it and from every batch with nothing to ask. The cloud decides: the same budget, cooldown and concurrency as any other capture (`product.md:122`), and a refusal is silence, because there is nothing the instrumentation would do differently."
+		}
 	},
 	$defs: {
 		"AgentInfo": {
@@ -65,6 +85,18 @@ var aggregates_schema_default = {
 					"type": "string",
 					"minLength": 1,
 					"maxLength": 64
+				},
+				"observers": {
+					"$ref": "#/$defs/Observers",
+					"description": "Absent from an instrumentation older than protocol 0.7.0. Absent is not 'nothing is observed': it is 'this one did not say', and the two must not be shown alike."
+				},
+				"withholding": {
+					"$ref": "#/$defs/Withholding",
+					"description": "Absent means **this sender did not say**, not that it withholds nothing — the same reading as `observers`, and for the same reason."
+				},
+				"resources": {
+					"$ref": "#/$defs/AgentResources",
+					"description": "What the instrumentation costs and what it has lost, measured by itself. Absent means **this sender did not say**, the same reading as `observers` and `withholding`. `product.md:239` asks for it by name: «recursos internos medidos»."
 				}
 			}
 		},
@@ -327,17 +359,9 @@ var aggregates_schema_default = {
 		},
 		"RuntimeHealth": {
 			"title": "RuntimeHealth",
-			"description": "Health of the agent's own process during the interval. Optional: an agent that does not measure it omits it. Per interval, not per route, because it belongs to the process.",
+			"description": "What the runtime itself was doing. Every field is optional and at least one has to be there: `product.md:251` says the protocol is independent of the language, and a Go runtime has garbage collection, a heap and a resident set but no event loop. Requiring the six of them meant it could either invent an event loop or send none of the three it does have. An empty object is not a reading, hence the minimum of one (gh-285).",
 			"type": "object",
 			"additionalProperties": false,
-			"required": [
-				"eventLoopDelayMs",
-				"gcPauseMs",
-				"gcCount",
-				"heapUsedMb",
-				"rssMb",
-				"inFlightMax"
-			],
 			"properties": {
 				"eventLoopDelayMs": {
 					"type": "object",
@@ -391,7 +415,8 @@ var aggregates_schema_default = {
 					"minimum": 0,
 					"description": "Peak concurrent in-flight requests during the interval."
 				}
-			}
+			},
+			"minProperties": 1
 		},
 		"Dependency": {
 			"title": "Dependency",
@@ -565,12 +590,522 @@ var aggregates_schema_default = {
 					"type": "integer",
 					"minimum": 0,
 					"description": "Only on the `(other)` bucket: how many distinct operations it merges, so a cap does not become a lie by omission."
+				},
+				"class": {
+					"enum": [
+						"select",
+						"insert",
+						"update",
+						"delete",
+						"other"
+					],
+					"description": "What kind of statement this is, when the sender could not normalise it safely. Its presence is the reason the text is absent: `product.md:104` says a query the normaliser does not understand travels «solo como hash y clase», and this is the class. Never sent together with `text` — they are two answers to the same question. Our word and not the service's: it is decided from the first keyword, which is all that can be told without understanding the rest (gh-344)."
+				}
+			},
+			"not": {
+				"required": ["class", "text"],
+				"properties": {
+					"class": {},
+					"text": {}
+				}
+			}
+		},
+		"ObserverState": {
+			"title": "ObserverState",
+			"enum": [
+				"on",
+				"off",
+				"unavailable"
+			],
+			"description": "Whether an observer is attached (`on`), was not asked for (`off`), or was asked for and could not attach (`unavailable`) — a driver that is not resolvable from the application's root, for instance. The third one is the point: without it, a service that is not being watched looks exactly like a service that has nothing to watch (COB-01, invariant 14)."
+		},
+		"Observers": {
+			"title": "Observers",
+			"type": "object",
+			"additionalProperties": false,
+			"description": "What the instrumentation is watching, by switch. The keys are the switches of `DOWNTRACE_INSTRUMENT`, so this says `pg` where a dependency says `postgres`: one is the switch and the other is the thing observed.",
+			"properties": {
+				"pg": { "$ref": "#/$defs/ObserverState" },
+				"http": { "$ref": "#/$defs/ObserverState" },
+				"redis": { "$ref": "#/$defs/ObserverState" },
+				"runtime": { "$ref": "#/$defs/ObserverState" }
+			}
+		},
+		"Withholding": {
+			"title": "Withholding",
+			"type": "object",
+			"additionalProperties": false,
+			"minProperties": 1,
+			"description": "What this sender is deliberately not sending, so that less arriving can be read as a choice rather than as a fault (invariant 14, COB-01). Counts and never names: the name of an excluded endpoint is exactly what the user asked not to send. The cloud cannot verify any of this and does not try — it is what the sender says, and it is shown as such.",
+			"properties": {
+				"freeText": {
+					"type": "boolean",
+					"description": "True when the sender is in minimal mode: no query text, no route templates, no dependency hosts, no error messages. Only ever true — a sender that is not in minimal mode leaves it out.",
+					"const": true
+				},
+				"endpoints": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "How many endpoints are excluded. Absent means none are."
+				},
+				"dependencies": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "How many dependencies are excluded. Absent means none are."
+				}
+			}
+		},
+		"CaptureProgress": {
+			"title": "CaptureProgress",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "startedAt"],
+			"description": "What the instrumentation has to say about a capture the cloud asked it for. The order travels in the ingest response (ADR 0071) and the answer travels here, on the same cadence and at the same cost: a path of its own would be one more call per capture, and one more thing to authenticate, for a fact that fits in the batch that is already going (gh-378).",
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "The capture's id, as the ingest response gave it. Carries nothing the service wrote."
+				},
+				"startedAt": {
+					"type": "integer",
+					"description": "Unix milliseconds when observation **really** started, which CAP-01 keeps apart from when the capture was accepted."
+				}
+			}
+		},
+		"ProcessException": {
+			"title": "ProcessException",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"kind",
+				"hash",
+				"count"
+			],
+			"description": "Something thrown outside any instrumented operation: an exception nobody caught, or a promise rejected with no `catch`. `product.md:77` asks for «errores **y excepciones**», and these are the two the word «excepciones» names. They live on the batch and not in the profile because they have **no route** — they happen outside a request's life, or after it ended — and filing them under a route that is not theirs would be worse than not having them (gh-341, ADR 0102).",
+			"properties": {
+				"kind": {
+					"enum": ["uncaught", "unhandled-rejection"],
+					"description": "Which of the two. Two different failures with two different fixes: counting them together hides which one is happening."
+				},
+				"hash": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "Stable identity of the signature, the same shape a query's or an operation error's has (ADR 0017)."
+				},
+				"text": {
+					"type": "string",
+					"maxLength": 512,
+					"description": "Type, sanitised message and stack signature. Optional and for the same reason as everywhere else: when nothing recognisable survives the sanitising, only the type and the signature travel (ADR 0084). Its absence is not the absence of an exception."
+				},
+				"count": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "How many times this signature happened. An instant per occurrence would be a row per crash of a process that crashes in a loop; what a reader asks is how many."
+				}
+			}
+		},
+		"LocalTrigger": {
+			"type": "object",
+			"title": "LocalTrigger",
+			"additionalProperties": false,
+			"required": ["signal", "observedAt"],
+			"description": "One local signal, sustained past its threshold. It asks for detail; it does not claim a cause (invariant 7).",
+			"properties": {
+				"signal": {
+					"type": "string",
+					"enum": ["event-loop-delay"],
+					"description": "Which signal fired. An enum and not free text: the cloud files findings by footprint, and a trigger type nobody can compare is a footprint that never matches. `product.md:114` names the absolute-threshold signals; this is the first of them."
+				},
+				"observedAt": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Unix milliseconds when the signal was last seen over its threshold. Milliseconds and not a date string because that is how this contract writes an instant —an interval's `start`, a capture's `startedAt`— and the evidence, which writes dates, is a different payload with different readers."
+				},
+				"valueMs": {
+					"type": "number",
+					"minimum": 0,
+					"description": "What was measured: the p99 of the event loop delay over the interval that fired."
+				},
+				"thresholdMs": {
+					"type": "number",
+					"minimum": 0,
+					"description": "The threshold it passed, sent with the value because a number without its threshold cannot be read by anyone who does not have this version of the instrumentation in front of them."
+				},
+				"intervals": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "How many consecutive intervals it stayed over. More than one is what makes it sustained rather than a spike (`product.md:114`)."
+				}
+			}
+		},
+		"AgentResources": {
+			"title": "AgentResources",
+			"type": "object",
+			"additionalProperties": false,
+			"description": "The instrumentation's own resources. Every field is optional and **absent is not zero**: an older sender says nothing, and a cloud that read that as «nothing was lost» would be inventing the one answer this exists to stop it inventing (invariant 14). The counters are differences since the previous batch, like everything else here; the two that are instants say so.",
+			"properties": {
+				"droppedBatches": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Batches the instrumentation threw away because its queue was full, since the previous batch. This is telemetry that existed and is gone: the number that separates «nothing happened» from «nothing arrived»."
+				},
+				"rejectedBatches": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Batches the cloud refused as invalid, since the previous batch. Nothing broke: something was sent wrong."
+				},
+				"failedBatches": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Batches that could not be sent —network, timeout, a cloud that was not there— since the previous batch. Not the same as dropped: these are retried, and only become loss if the queue fills."
+				},
+				"internalErrors": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Errors inside the instrumentation itself, since the previous batch. It disables itself after enough of them, and a sender that has gone quiet with these climbing is not a quiet service."
+				},
+				"bufferBytes": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "What the black box's registers have allocated, right now. An instant, and arithmetic rather than a measurement: the rings are preallocated."
+				},
+				"hookMsPerRequest": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Estimated milliseconds of the instrumentation's own hooks per request. **An estimate**, sampled, and named as one: it is what invariant 3 budgets, and reporting it as an exact measurement would claim a precision the sampling does not have."
+				},
+				"shed": {
+					"type": "string",
+					"enum": [
+						"nothing",
+						"fine",
+						"profile"
+					],
+					"description": "What the instrumentation has given up because it was costing too much, cheapest loss first. `product.md:241` asks for both halves —«se autolimita» and «lo registra como pérdida de cobertura»— and this is the second. An enum and not free text: it is ours, and it has to be comparable between senders."
+				},
+				"shedReason": {
+					"type": "string",
+					"enum": ["latency", "memory"],
+					"description": "Why it gave ground. Absent when nothing was given up."
+				}
+			}
+		}
+	}
+};
+//#endregion
+//#region schema/v0/capture-evidence.schema.json
+var capture_evidence_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://downtrace.io/schema/v0/capture-evidence.schema.json",
+	title: "CaptureEvidence",
+	description: "What an instrumentation sends back for a capture the cloud asked for (POST /v0/captures/{id}/evidence). It is the contents of the black box's fine register, frozen: requests with their operations, in order, with starts and ends. Hashes only — the text of a query never travels here (invariant 5). Its own path and not the aggregates batch, because a batch is what goes out every ten seconds and this is a rare event several orders of magnitude larger.",
+	"x-evidence-path": "/v0/captures/{id}/evidence",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"protocol",
+		"instance",
+		"startedAt",
+		"endedAt",
+		"coverage",
+		"requests"
+	],
+	properties: {
+		"protocol": {
+			"type": "string",
+			"description": "Protocol version this payload conforms to. Same enum as a batch: every published minor of v0 stays acceptable.",
+			"enum": [
+				"0.1.0",
+				"0.2.0",
+				"0.3.0",
+				"0.4.0",
+				"0.5.0",
+				"0.6.0",
+				"0.7.0"
+			]
+		},
+		"instance": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id"],
+			"description": "Which process observed this. Several instances of one deployment get the same order on purpose (ADR 0071), so the cloud has to be able to tell two answers apart.",
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 128
+				},
+				"hostname": {
+					"type": "string",
+					"maxLength": 253
+				},
+				"pid": {
+					"type": "integer",
+					"minimum": 0
+				}
+			}
+		},
+		"startedAt": {
+			"type": "string",
+			"format": "date-time",
+			"description": "The **effective start of observation**, which is the instant CAP-01 insists on keeping apart from the acceptance. It travels with the evidence rather than in a call of its own: a capture that started and never finished should not cost two requests."
+		},
+		"endedAt": {
+			"type": "string",
+			"format": "date-time",
+			"description": "When the instrumentation stopped watching."
+		},
+		"coverage": { "$ref": "#/$defs/Coverage" },
+		"requests": {
+			"type": "array",
+			"maxItems": 4096,
+			"items": { "$ref": "#/$defs/CapturedRequest" },
+			"description": "The requests observed, oldest first. An empty array is a real answer and the commonest one: a route nobody called during the window. It means the capture is `empty`, and `product.md:192` is explicit that this must never read as an invitation to ask again unchanged."
+		},
+		"reference": { "$ref": "#/$defs/Reference" }
+	},
+	$defs: {
+		"Coverage": {
+			"type": "object",
+			"title": "CaptureCoverage",
+			"additionalProperties": false,
+			"required": [
+				"observedRequests",
+				"attachedRequests",
+				"detailLost",
+				"truncated"
+			],
+			"description": "`product.md:192` asks a capture to declare **both** coverages: what it attached from detail still retained, and what it observed from its effective start. Two numbers, never one — a total would hide that half of it is older than the capture.",
+			"properties": {
+				"observedRequests": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Requests seen from the effective start onwards."
+				},
+				"attachedRequests": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Requests that were already in the register when the capture started, and are attached. Zero is normal: the register may have wrapped, and nothing brings back what was not kept."
+				},
+				"detailLost": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Requests whose operations were overwritten before they could be read. Their timing is still true; what is gone is the detail. Reported rather than dropped, because a request with no operations reads as one that ran nothing (invariant 14)."
+				},
+				"truncated": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Requests that ran more operations than the register keeps per request. Their count is real and their list is not complete."
+				}
+			}
+		},
+		"CapturedRequest": {
+			"type": "object",
+			"title": "CapturedRequest",
+			"additionalProperties": false,
+			"required": [
+				"method",
+				"route",
+				"status",
+				"startedAt",
+				"durationMs",
+				"operations"
+			],
+			"properties": {
+				"method": {
+					"type": "string",
+					"maxLength": 16
+				},
+				"route": {
+					"type": "string",
+					"maxLength": 512,
+					"description": "The route template, never the path with its values in it (invariant 5)."
+				},
+				"status": {
+					"type": "integer",
+					"minimum": 100,
+					"maximum": 599
+				},
+				"startedAt": {
+					"type": "string",
+					"format": "date-time",
+					"description": "When this request started. Absolute, so requests from two instances can be read side by side."
+				},
+				"durationMs": {
+					"type": "number",
+					"minimum": 0
+				},
+				"operations": {
+					"type": "array",
+					"maxItems": 256,
+					"items": { "$ref": "#/$defs/CapturedOperation" },
+					"description": "What it ran, in the order it started them. Empty means it ran nothing — unless `detailLost` says the list was overwritten, which is why that flag is on the request and not only in the totals."
+				},
+				"truncated": {
+					"type": "boolean",
+					"description": "This request ran more operations than the register keeps per request. Absent means false."
+				},
+				"detailLost": {
+					"type": "boolean",
+					"description": "This request's operations were overwritten before they were read. Absent means false. Its timing is still true."
+				}
+			}
+		},
+		"CapturedOperation": {
+			"type": "object",
+			"title": "CapturedOperation",
+			"additionalProperties": false,
+			"required": [
+				"hash",
+				"startMs",
+				"endMs"
+			],
+			"description": "One operation inside a request. Starts and ends and not durations, because the whole reason for capturing detail is order and overlap, which a duration cannot express (ADR 0068).",
+			"properties": {
+				"hash": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "The fingerprint's hash. Never the text: the profile is where a sender chooses whether to ship the text of its queries, and this path never carries it (invariant 5, ADR 0017)."
+				},
+				"startMs": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Milliseconds from the start of its own request."
+				},
+				"endMs": {
+					"type": "number",
+					"minimum": 0
+				}
+			}
+		},
+		"Reference": {
+			"type": "object",
+			"title": "ReferenceSamples",
+			"additionalProperties": false,
+			"required": [
+				"selection",
+				"population",
+				"samples"
+			],
+			"description": "A few requests of each endpoint kept as something to compare the captured ones against. `product.md:100`: «Comparar requests degradadas con requests de referencia exige conservar ambas; el detalle fino de hace una hora ya no existe». Being earlier does not certify health, which is why every field here is about how they were chosen and none of them says «healthy».",
+			"properties": {
+				"selection": {
+					"type": "string",
+					"enum": ["uniform-reservoir"],
+					"description": "How they were chosen. Travels with them because a sample whose selection is unknown cannot support an attribution (ATR-01). `uniform-reservoir`: every request observed of that endpoint had the same chance of being kept, whatever it did — which is what «the fastest N» would not be."
+				},
+				"population": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "How many requests they were drawn from, over the life of the sending process."
+				},
+				"routesDropped": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Endpoints seen that the register had no room for. Counted rather than silently absent: an endpoint with no samples is not an endpoint with no traffic (invariant 14)."
+				},
+				"renewalPaused": {
+					"type": "boolean",
+					"description": "True when requests were observed that the register deliberately did not consider. The instrumentation pauses renewal while it is watching a capture, which is the closest it can get to REF-01 from inside the process: it cannot know whether an incident is open, but it knows detail has been asked of it. Absent means false."
+				},
+				"samples": {
+					"type": "array",
+					"maxItems": 64,
+					"items": { "$ref": "#/$defs/CapturedRequest" },
+					"description": "The kept requests, in the same shape as the captured ones. An empty array is a real answer: a process that has just started has nothing to compare with yet."
 				}
 			}
 		}
 	}
 };
 //#endregion
+//#region schema/v0/ingest-response.schema.json
+var ingest_response_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://downtrace.io/schema/v0/ingest-response.schema.json",
+	title: "IngestResponse",
+	description: "What the cloud answers to POST /v0/aggregates. Described here, and not left as an implementation detail, because since protocol 0.7.0 it carries instructions: the captures the cloud is waiting for. It follows the same rules as the batch — fields are only ever added, each addition bumps the minor, and a published minor is accepted for ever — with one difference in who owes what. An agent that does not read this body must behave exactly as it did before (ADR 0008), so every field here is something an agent may ignore.",
+	type: "object",
+	additionalProperties: false,
+	required: ["accepted", "inserted"],
+	properties: {
+		"accepted": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "How many intervals of the batch the cloud took."
+		},
+		"inserted": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "How many rows were new. Lower than `accepted` when a batch is re-sent: ingest is idempotent."
+		},
+		"captures": {
+			"type": "array",
+			"maxItems": 16,
+			"items": { "$ref": "#/$defs/PendingCapture" },
+			"description": "Captures the cloud is waiting for, in the environment this batch came from. Absent or empty means none. Bounded because this rides on every batch: the cloud never asks for more at once than an instrumentation could reasonably freeze, and the concurrency budget is far below this anyway. Several instances of one deployment receive the same list on purpose — the cloud knows which instance sent recently, not which is alive, so dealing one capture to one instance would lose it silently when that process is gone (invariant 14)."
+		}
+	},
+	$defs: { "PendingCapture": {
+		"type": "object",
+		"title": "PendingCapture",
+		"additionalProperties": false,
+		"required": [
+			"id",
+			"windowSeconds",
+			"expiresAt"
+		],
+		"properties": {
+			"id": {
+				"type": "string",
+				"minLength": 1,
+				"maxLength": 64,
+				"description": "What the evidence will be sent back under. Carries nothing the service wrote."
+			},
+			"environment": {
+				"type": "string",
+				"maxLength": 128,
+				"description": "The environment this capture is about, which is always the one the batch came from. Sent anyway so the payload is readable on its own."
+			},
+			"method": {
+				"type": "string",
+				"maxLength": 16,
+				"description": "HTTP method of the route to watch."
+			},
+			"route": {
+				"type": "string",
+				"maxLength": 512,
+				"description": "Route template to watch. Empty when the capture is about a dependency rather than a route."
+			},
+			"kind": {
+				"type": "string",
+				"maxLength": 32,
+				"description": "Dependency kind to watch. Empty when the capture is about a route."
+			},
+			"target": {
+				"type": "string",
+				"maxLength": 256,
+				"description": "Dependency target to watch."
+			},
+			"windowSeconds": {
+				"type": "integer",
+				"minimum": 1,
+				"maximum": 600,
+				"description": "How long to watch for, from the effective start of observation."
+			},
+			"expiresAt": {
+				"type": "string",
+				"format": "date-time",
+				"description": "After this instant the cloud stops waiting. An instrumentation that reads a stale response must not start a capture past it: the cloud will refuse the evidence, and a capture nobody is waiting for spends the fine register for nothing."
+			}
+		}
+	} }
+};
+//#endregion
 //#region src/generated/boundaries.ts
 /** Upper bounds (ms) of the fixed latency buckets; the last bucket is open-ended. */
 const LATENCY_BOUNDARIES_V0 = [
@@ -627,6 +1162,12 @@ const CALLS_PER_REQUEST_BUCKETS_V0 = 8;
 //#region src/generated/paths.ts
 /** Path, relative to the ingest URL, that receives AggregatesBatch payloads. */
 const AGGREGATES_PATH = "/v0/aggregates";
+/** Path template that receives a capture's evidence. `{id}` is the capture's identifier. */
+const CAPTURE_EVIDENCE_PATH = "/v0/captures/{id}/evidence";
+/** The evidence path for one capture. Here rather than in every caller: one place builds it (gh-322). */
+function captureEvidencePath(id) {
+	return CAPTURE_EVIDENCE_PATH.replace("{id}", encodeURIComponent(id));
+}
 //#endregion
 //#region src/generated/versions.ts
 /** Every published minor of v0, oldest first. The cloud never stops accepting one it published (ADR 0008). */
@@ -636,14 +1177,26 @@ const ACCEPTED_PROTOCOL_VERSIONS_V0 = [
 	"0.3.0",
 	"0.4.0",
 	"0.5.0",
-	"0.6.0"
+	"0.6.0",
+	"0.7.0"
 ];
 /** The newest published minor: what an up-to-date agent stamps on every batch. */
-const PROTOCOL_VERSION = "0.6.0";
+const PROTOCOL_VERSION = "0.7.0";
 //#endregion
 //#region src/index.ts
 /** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
 const AGGREGATES_SCHEMA_V0 = aggregates_schema_default;
+/**
+* The JSON Schema for what the cloud answers. A contract since 0.8.0, when the answer started carrying the
+* captures the cloud is waiting for: an agent that ignores this body behaves exactly as it always did.
+*/
+const INGEST_RESPONSE_SCHEMA_V0 = ingest_response_schema_default;
+/**
+* The JSON Schema for a capture's evidence: the black box's fine detail, frozen and sent back. Its own path
+* and its own contract, because a batch goes out every ten seconds and this is a rare event several orders of
+* magnitude larger.
+*/
+const CAPTURE_EVIDENCE_SCHEMA_V0 = capture_evidence_schema_default;
 /** Index of the bucket a latency (ms) falls into: first boundary >= latency, else the open-ended last bucket. */
 function latencyBucket(ms) {
 	const n = LATENCY_BOUNDARIES_V0.length;
@@ -663,4 +1216,4 @@ function callsPerRequestBucket(calls) {
 	return n;
 }
 //#endregion
-export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, callsPerRequestBucket, latencyBucket };
+export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, CAPTURE_EVIDENCE_PATH, CAPTURE_EVIDENCE_SCHEMA_V0, INGEST_RESPONSE_SCHEMA_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, callsPerRequestBucket, captureEvidencePath, latencyBucket };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downtrace/protocol",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Downtrace ingestion protocol: JSON Schema, fixtures and generated TypeScript types",
   "type": "module",
   "exports": {