@olivervea/pipelines 2.0.0-beta.17 → 2.0.0-beta.18

package/README.md

@@ -253,6 +253,7 @@ export default pipeline({ name: "Olve.Pipelines", description: "…", input: M.D
 - **Describe checks the mapper twice.** It records the mapper with proxies, and it statically analyses the mapper's source. The source must be an object literal of member chains, literals, constant arrays and nested object literals. Ternaries, `&&`, `||`, `??`, `!`, comparisons, arithmetic, template strings, calls, spread and optional chaining are all rejected. Free identifiers such as module constants are allowed; they are recorded as `{const}`.
 - **Triggers.** A pipeline may call `onPush` at most once. Each `onPoll` and `onWebhook` needs a distinct `name` (`onPoll` defaults to `"poll"`). `onWebhook({ name, verify }, ({ headers, body }) => input | null)` maps a delivery to `/api/hooks/<pipeline id>/<name>`; `verify` is `hmacSha256({ secret, header, prefix? })`, `githubSignature(secret)` or `bearer(secret)`, and `null` ignores the delivery.
 - **`select` (branch on config).** `.select(TARGET.prod, { ssh: (p, prod) => p.stage(…), inCluster: (p, prod) => p.stage(…) })`: the first argument references a `z.discriminatedUnion` in a config entry (`DiscriminatorOf<U>` is its one literal field; a union with no or several literal fields is a type error). Cases are exhaustive and checked at compile time; each gets the reference narrowed to its variant (`ConfigNode<VariantOf<U, D, V>>`), recorded as `{"$config": "target.prod", "$case": "target.prod.kind=ssh"}` and usable only inside that case. The manifest records `{select, discriminator, cases}`; the service resolves it per run from the pinned config snapshot (`when` is per run input). The same step name may appear in several cases (same output model; not two different custom steps, since handlers pair by name); a step every case has is definitely available afterwards, one only some have is maybe-available. The harness picks the variant of a same-named step from `OLVE_CASES` (a JSON array of the case conditions the step sits in, set by the service).
+- **Retention.** `pipeline({ …, retention: { keepLatestRuns?, minRunAgeDays?, buildGraceDays? } })` overrides the instance's retention thresholds for this pipeline's runs and binaries, field by field (non-negative integers; unset = the instance's value). Recorded on the manifest root as `retention`; the service applies the active version's.
 - **Failure handlers.** `.onFailure(handler, { steps? })` takes a step whose inputs are all `FailureContext`. When a run fails, the service runs each handler whose scope (default: any step) contains a failed step, once per failure: `run <handler>` in the handler's image with its declared secrets, from the run's pinned binary. It is untracked and best-effort — not an attempt of the run, never retried, and its own failure triggers nothing; its log is kept at `runs/<p>/<run>/_failure/<handler>/<id>/log`. `FailureContext` carries `pipeline {id, name}`, `run {id, number, address, versionStamp, trigger, url}`, `version {number, commit}`, the run's `input`, a one-line `reason`, and `failedSteps[]` (`step, attempt, address, reason, logUrl`) — only the steps in the handler's scope, never empty.
 
 ### Testing handlers
@@ -397,6 +398,7 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
   - `{kind: "poll", name, url, headers, secrets, valuePath, intervalSeconds}`, where header values may contain `$SECRET:NAME`;
   - `{kind: "webhook", name, verify: {scheme: "hmac-sha256", secret, header, prefix} | {scheme: "bearer", secret}}`. The `map-trigger` event is `{headers, body}`; a `null` mapping yields a `skipped` envelope (the delivery is ignored).
 - **`failureHandlers`** is a list of `{step: Step, steps: [names] | null}`. Each handler's inputs are all FailureContext (`{"ref": "failure"}`).
+- **`retention`** (when present) is `{keepLatestRuns?, minRunAgeDays?, buildGraceDays?}`, non-negative integers that replace the instance's thresholds for this pipeline. Omitted when the definition sets none.
 - **`secrets`** lists every secret used by steps, polls and webhooks, sorted, as `{name, description}`.
 - **`config`** lists every config entry steps declare, sorted by name, as `{name, description, required, schema}`. `schema` is the `z.input` view (defaults listed); it validates the entry's value in the config document. `required` is false when the schema accepts a missing value. A `secretRef` field is marked `"x-olve-kind": "secretRef"`, with the secret's name as `properties.secret.const`. Omitted when there are no entries.
 - **Step `configEntries`** names the entries the step receives (sorted; omitted when none). It is part of the step's content, like `secrets`. The step key `config` is the step's `settings`.

package/manifest.schema.json

@@ -165,6 +165,28 @@
           "minLength": 1,
           "type": "string"
         },
+        "retention": {
+          "additionalProperties": false,
+          "description": "Retention overrides for this pipeline (omitted when none). Each field replaces the instance setting of the same meaning.",
+          "properties": {
+            "buildGraceDays": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "keepLatestRuns": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "minRunAgeDays": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            }
+          },
+          "type": "object"
+        },
         "secrets": {
           "description": "All declared secrets (steps + poll triggers), sorted by name.",
           "items": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olivervea/pipelines",
-  "version": "2.0.0-beta.17",
+  "version": "2.0.0-beta.18",
   "description": "Olve.Pipelines v2 SDK: typed pipeline authoring, the step harness, and the build tool.",
   "type": "module",
   "license": "MIT",

package/src/builder/pipeline.ts

@@ -183,10 +183,21 @@ export interface FailureHandlerNode {
   readonly steps: readonly AnyStep[] | null;
 }
 
+/** Per-pipeline retention; each field overrides the instance's `Retention:*` setting of the same meaning. */
+export interface RetentionPolicy {
+  /** A run is never deleted while among its pipeline's newest N runs. */
+  keepLatestRuns?: number;
+  /** A run is never deleted while younger than this. */
+  minRunAgeDays?: number;
+  /** An unused compiled binary is deleted this long after it was last modified. */
+  buildGraceDays?: number;
+}
+
 export interface PipelineData {
   readonly name: string;
   readonly description: string | undefined;
   readonly input: AnyModel;
+  readonly retention: RetentionPolicy | undefined;
   readonly nodes: StageNode[];
   readonly triggers: TriggerNode[];
   readonly failureHandlers: FailureHandlerNode[];
@@ -216,6 +227,8 @@ export interface PipelineDef<In extends AnyModel> {
   description?: string;
   /** The pipeline input model (what triggers produce, what `when` matches on). */
   input: In;
+  /** Retention overrides for this pipeline's runs and binaries (unset fields keep the instance's values). */
+  retention?: RetentionPolicy;
 }
 
 export class Pipeline<In extends AnyModel, A extends AvailMap> {
@@ -228,6 +241,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
       name: def.name,
       description: def.description,
       input: def.input,
+      retention: def.retention,
       nodes: [],
       triggers: shared?.triggers ?? [],
       failureHandlers: shared?.failureHandlers ?? [],

package/src/describe/describe.ts

@@ -488,6 +488,15 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     return { kind: "poll", name: t.name, url: t.url, headers: { ...t.headers }, secrets: [...declared].sort(), valuePath: t.valuePath, intervalSeconds: t.intervalSeconds };
   });
 
+  // ── retention ──
+  const retention: Record<string, number> = {};
+  for (const key of ["keepLatestRuns", "minRunAgeDays", "buildGraceDays"] as const) {
+    const v = data.retention?.[key];
+    if (v === undefined) continue;
+    if (!(Number.isInteger(v) && v >= 0)) problems.push(`retention.${key} must be a non-negative integer`);
+    else retention[key] = v;
+  }
+
   if (problems.length) throw new DescribeError(problems);
 
   const manifest = canonicalize({
@@ -495,6 +504,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     name: data.name,
     description: data.description,
     input: inputModel.name,
+    ...(Object.keys(retention).length ? { retention } : {}),
     harness: opts.harness,
     models: Object.fromEntries([...models].map(([k, v]) => [k, v.schemas])),
     secrets: [...secrets].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([name, description]) => ({ name, description })),

package/src/describe/manifest-schema.ts

@@ -182,6 +182,14 @@ export const Manifest = z
       )
       .optional()
       .describe("Config entries used by steps, sorted by name (omitted when none). Fields of kind secretRef ({secret: NAME}) name a secret."),
+    retention: z
+      .strictObject({
+        keepLatestRuns: z.int().min(0).optional(),
+        minRunAgeDays: z.int().min(0).optional(),
+        buildGraceDays: z.int().min(0).optional(),
+      })
+      .optional()
+      .describe("Retention overrides for this pipeline (omitted when none). Each field replaces the instance setting of the same meaning."),
     triggers: z.array(Trigger),
     stages: z.array(Stage),
     failureHandlers: z.array(

package/src/index.ts

@@ -12,5 +12,5 @@ export type { Simplify } from "./core/types.ts";
 export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";
 export type { Ctx, RunInfo, Sh, ShOptions, ExecOptions, Http, HttpInit, RetryOptions, OutputFileOptions } from "./ctx/types.ts";
 export type { Ref, Mappable, MapperResult } from "./builder/refs.ts";
-export { pipeline, Pipeline, type PipelineDef, type InRefs, type InitialAvail, type WhenCond, type PushEvent, type StageEntry, type CheckStage, type MapperFn } from "./builder/pipeline.ts";
+export { pipeline, Pipeline, type PipelineDef, type RetentionPolicy, type InRefs, type InitialAvail, type WhenCond, type PushEvent, type StageEntry, type CheckStage, type MapperFn } from "./builder/pipeline.ts";
 export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type RegistryAuthConfig, type HelmDeployOverSshDef, helmTarget, deployTarget, type DeployTargetOptions, type ComposeDeployDef, type ComposeTargetValue, type HelmDeployInClusterDef, type HelmDeploySshTargetDef, type HelmTargetDeployDef, type HelmTargetValue, type InClusterTargetValue, type SshTargetValue, httpHealthCheck, type HttpHealthCheckOptions, sshSession, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";