akanjs 3.0.2 → 3.1.0-rc.0

package/signal/types.ts

@@ -1,5 +1,5 @@
 import type { DefaultPrimitiveName, UnCls } from "akanjs/base";
-import type { ServiceModel } from "akanjs/service";
+import type { AkanJob, ServiceModel } from "akanjs/service";
 import type { RateLimitBudget } from "./endpointRateLimit";
 import type { GuardCls } from "./guard";
 import type { MiddlewareCls } from "./middleware";
@@ -89,6 +89,11 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
    * it. Losing the race does not stop the handler, which runs to completion with nobody holding its result.
    */
   timeout?: number;
+  /**
+   * A `process` job that failed its last attempt, with `this` the internal: the dead letter, called once per job on
+   * whichever queue ran it. Throwing from it is logged and changes nothing.
+   */
+  onFailed?: (this: any, job: AkanJob, error: unknown) => Promise<void> | void;
   partial?: _Key[] | readonly _Key[];
   /**
    * Milliseconds to reuse the answer, keyed by endpoint and arguments; unset caches nothing. Only a `query` with no
@@ -191,6 +196,8 @@ export interface SerializedSignal {
   crud?: SerializedSignalMcp;
   /** Which generated CRUD verbs a person-only guard protects, by the same verb map; only the `false` keys travel. */
   agents?: SerializedSignalMcp;
+  /** The app or lib that registered the signal, first registrant first: an app extending a lib module reads `["shared", "sceny"]`. */
+  origin?: string[];
 }
 
 /** Keyed by generated verb, mirroring the `guards` map `slice()` takes. The root slice's own flag rides on `slice[""]`. */
@@ -203,7 +210,10 @@ export interface SerializedSignalMcp {
 
 export type SignalType = "restapi" | "websocket";
 
-export type WebsocketReqData = { key: string; data: unknown[]; subscribe?: boolean };
+/** Where a client's copy of a room stands: the numbering it came from, and the last frame it took. */
+export type WebsocketRoomCursor = { epoch: string; seq: number };
+/** `since` asks a resubscribe to send what was published after it, if the server still can. */
+export type WebsocketReqData = { key: string; data: unknown[]; subscribe?: boolean; since?: WebsocketRoomCursor };
 export type WebsocketMessageData = { type: "msg"; key: string; data: object | object[] };
 /**
  * `op` is relative to the room, not the database: a row edited out of a filter is `leave` there and `enter` where it
@@ -224,7 +234,12 @@ export type WebsocketSubscribeAck = {
   roomId: string;
   requestRoomId: string;
   subscribe: boolean;
+  /** The room's numbering at the subscribe, when the server numbers its frames. */
+  cursor?: WebsocketRoomCursor;
+  /** Answering `since`: `true` when every frame after it was sent ahead of this ack, `false` for a gap. */
+  replayed?: boolean;
 };
-export type WebsocketPublishData = { type: "pub"; roomId: string; data: object | object[] };
+/** `seq` numbers the frames one server process delivers for a room, one apart. */
+export type WebsocketPublishData = { type: "pub"; roomId: string; data: object | object[]; seq?: number };
 export type WebsocketAuthAck = { type: "auth"; revokedRooms: string[] };
 export type WebsocketResData = WebsocketMessageData | WebsocketSubscribeAck | WebsocketPublishData | WebsocketAuthAck;

package/store/agent/StoreSurfaceSource.ts

@@ -52,8 +52,8 @@ export class StoreSurfaceSource implements SurfaceSource {
           : "path must be an internal path starting with /.",
       run: async (args) => {
         const path = String(args.path);
-        router.push(path);
         try {
+          router.push(path);
           await router.navigation();
         } catch {
           throw new Error(

package/store/agentic/StToolBuilder.ts

@@ -33,6 +33,8 @@ export interface StToolMeta {
   settle?: boolean;
   confirm?: ToolConfirm;
   guard?: ToolGuard;
+  /** What a person reads for this action in a command palette, in their language (an `l()` result); never the model. */
+  label?: string;
 }
 
 /** A scalar, an enum, or one array level of either. */
@@ -141,6 +143,7 @@ export class StToolBuilder<Args extends unknown[] = []> {
         description: spec.desc,
         settle: spec.meta.settle,
         parameters: StToolBuilder.parametersOf(spec.args),
+        label: () => live.current.meta.label,
         
         ...(spec.meta.confirm === undefined && !name.startsWith("remove")
           ? {}

package/test/conformance.ts

@@ -4,7 +4,6 @@ import path from "node:path";
 import {
   DEFAULT_TOKENIZER,
   getSolidConfig,
-  LibsqlDatabase,
   PostgresDatabase,
   PostgresDialect,
   RedisCache,
@@ -16,12 +15,11 @@ import {
   SqliteDialect,
 } from "akanjs/service";
 
-type ConformanceBackend = "redis" | "postgres" | "libsql";
+type ConformanceBackend = "redis" | "postgres";
 
 export type ConformanceCacheKind = "solid" | "redis";
 
-/** `libsqlRemote` is a sqld server shared by every run, so it only hosts cases that bring their own table. */
-export type SqlDriverKind = "sqlite" | "libsql" | "postgres" | "libsqlRemote";
+export type SqlDriverKind = "sqlite" | "postgres";
 
 export interface SqlDriverOptions {
   insight?: boolean;
@@ -31,7 +29,7 @@ export interface SqlDriverOptions {
 
 export interface SqlDriver {
   kind: SqlDriverKind;
-  database: SqliteDatabase | LibsqlDatabase | PostgresDatabase;
+  database: SqliteDatabase | PostgresDatabase;
   dialect: SqlDialect;
   /** A new adaptor on the same storage — what a process restart sees, so only what was committed. */
   restart: () => Promise<SqlDriver>;
@@ -45,10 +43,9 @@ export interface SqlDriver {
 const backendEnvNames = {
   redis: "AKAN_TEST_REDIS_URL",
   postgres: "AKAN_TEST_POSTGRES_URL",
-  libsql: "AKAN_TEST_LIBSQL_URL",
 } as const;
 
-/** `bun run testConformance` (`infra/test/compose.yaml`) sets all three backends; plain `bun test` runs SQLite. */
+/** `bun run testConformance` (`infra/test/compose.yaml`) sets both backends; plain `bun test` runs SQLite. */
 export class ConformanceEnv {
   static readonly #announced = new Set<string>();
   /** Where a deployment points an app at its data. A test that hands its storage in has these cleared first. */
@@ -56,9 +53,6 @@ export class ConformanceEnv {
     "AKAN_DATABASE_MODES",
     "AKAN_SOLID_DB_PATH",
     "SQLITE_DATABASE_PATH",
-    "LIBSQL_URL",
-    "LIBSQL_URI",
-    "LIBSQL_AUTH_TOKEN",
     "POSTGRES_URL",
     "POSTGRES_URI",
     "POSTGRES_HOST",
@@ -199,24 +193,12 @@ export class ConformanceEnv {
   }
 
   /** The local drivers always, and each remote one whose backend the suite can reach. */
-  static sqlDrivers(suite: string, { remote = false }: { remote?: boolean } = {}): SqlDriverKind[] {
+  static sqlDrivers(suite: string): SqlDriverKind[] {
     const kinds: SqlDriverKind[] = ["sqlite"];
-    if (ConformanceEnv.#hasLibsqlBinding(suite)) kinds.push("libsql");
     if (ConformanceEnv.has(suite, "postgres")) kinds.push("postgres");
-    if (remote && ConformanceEnv.has(suite, "libsql")) kinds.push("libsqlRemote");
     return kinds;
   }
 
-  static #hasLibsqlBinding(suite: string) {
-    if (process.platform !== "win32" || process.arch !== "arm64") return true;
-    const key = `${suite}:libsql-binding`;
-    if (!ConformanceEnv.#announced.has(key)) {
-      ConformanceEnv.#announced.add(key);
-      console.info(`[conformance] ${suite}: local libsql cases skipped — libsql publishes no win32-arm64 binding`);
-    }
-    return false;
-  }
-
   /**
    * The real adaptor, initialised as the DI container would, on storage nothing else sees. `insight` gives Postgres a
    * login role for `InsightQuery`; `memory` puts SQLite in memory, as `TestServer` does.
@@ -229,14 +211,12 @@ export class ConformanceEnv {
     kind: SqlDriverKind,
     { insight = false, memory = false, search: searchConfig }: SqlDriverOptions,
   ): Promise<{ config: object; remove: () => Promise<void> }> {
-    const search = { enabled: kind !== "libsqlRemote", tokenizer: DEFAULT_TOKENIZER, ...searchConfig };
+    const search = { enabled: true, tokenizer: DEFAULT_TOKENIZER, ...searchConfig };
     if (kind === "postgres") {
       const { url, insightUrl, drop } = await ConformanceEnv.postgresSchema("akan_sql", { insight });
       return { config: { url, insightUrl, search }, remove: drop };
     }
-    if (kind === "libsqlRemote")
-      return { config: { url: ConformanceEnv.url("libsql"), search }, remove: async () => undefined };
-    if (kind === "sqlite" && memory)
+    if (memory)
       return {
         config: { filePath: ":memory:", journalMode: "MEMORY", synchronous: "OFF", foreignKeys: true, search },
         remove: async () => undefined,
@@ -244,10 +224,7 @@ export class ConformanceEnv {
     const { dir, remove } = await ConformanceEnv.tempDir(`akan-${kind}`);
     const filePath = path.join(dir, "conformance.db");
     return {
-      config:
-        kind === "sqlite"
-          ? { filePath, journalMode: "WAL", busyTimeoutMs: 5000, synchronous: "NORMAL", foreignKeys: true, search }
-          : { url: `file:${filePath}`, search },
+      config: { filePath, journalMode: "WAL", busyTimeoutMs: 5000, synchronous: "NORMAL", foreignKeys: true, search },
       remove,
     };
   }
@@ -262,8 +239,7 @@ export class ConformanceEnv {
     storage: { config: object; remove: () => Promise<void> },
   ): Promise<SqlDriver> {
     const scheduler = new Scheduler();
-    const database =
-      kind === "postgres" ? new PostgresDatabase() : kind === "sqlite" ? new SqliteDatabase() : new LibsqlDatabase();
+    const database = kind === "postgres" ? new PostgresDatabase() : new SqliteDatabase();
     Object.assign(database, { scheduler, config: storage.config });
     await database.onInit();
     const shutdown = async () => {

package/types/base/baseEnv.d.ts

@@ -21,10 +21,6 @@ export type BackendEnv = {
             cacheSize?: number;
             tempStore?: string;
         };
-        libsql?: {
-            url?: string;
-            authToken?: string;
-        };
         postgres?: {
             url?: string;
             host?: string;

package/types/base/primitiveRegistry.d.ts

@@ -152,7 +152,7 @@ declare global {
         [CLIENT_VALUE]: Dayjs;
         [DEFAULT_VALUE]: Dayjs;
         [PURIFIED_VALUE]: Dayjs;
-        [EXAMPLE_VALUE]: string;
+        [EXAMPLE_VALUE]: Dayjs;
         validate(value: Date): boolean;
         parseValue(input: Date): Dayjs;
         serializeValue(value: Dayjs | Date): Date;

package/types/client/csrLocation.d.ts

@@ -0,0 +1,32 @@
+export interface CsrMemoryOwner {
+    leave: (href: string) => void;
+    reload: () => void;
+}
+declare global {
+    var __AKAN_CSR_LOCATION__: CsrLocation | undefined;
+    var __AKAN_EMBED__: {
+        kind: "mcp-app";
+        origin?: string;
+        account?: Record<string, unknown> | null;
+    } | undefined;
+}
+export declare class CsrLocation {
+    #private;
+    get isMemory(): boolean;
+    /** The owner takes what a document load would do, which a view cannot: it has no document to load in its place. */
+    useMemory(href: string, owner: CsrMemoryOwner): void;
+    /** Path, search and hash, without the origin. */
+    get href(): string;
+    get pathname(): string;
+    get search(): string;
+    get hash(): string;
+    get state(): unknown;
+    /** `href` as a route reads it: an absolute URL on this document's origin loses the origin, anything else is kept. */
+    strip(href: string): string;
+    push(state: unknown, href: string): void;
+    replace(state: unknown, href?: string): void;
+    back(): void;
+    assign(href: string): void;
+    reload(): void;
+}
+export declare const csrLocation: CsrLocation;

package/types/client/csrTypes.d.ts

@@ -14,13 +14,22 @@ export type PageSafeAreaConfig = boolean | "top" | "bottom" | {
 /** `"stream"` flushes the shell (`Loading` included) then streams; a redirect in suspended content becomes a client one.
  * `"block"` buffers the whole document, so an error in slow content can still render a clean error page. */
 export type SsrRenderMode = "stream" | "block";
+/** Px per Tailwind breakpoint (sm 40rem, md 48rem, lg 64rem, xl 80rem, 2xl 96rem), each from its own width up. */
+export interface ResponsiveInset {
+    base: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    "2xl"?: number;
+}
 export interface PageConfig {
     transition?: TransitionType;
     safeArea?: PageSafeAreaConfig;
-    /** Top chrome reservation in px. Use true for the default 48px reservation. */
-    topInset?: number | boolean;
-    /** Bottom chrome reservation in px. Use true for the default 48px reservation. */
-    bottomInset?: number | boolean;
+    /** Top chrome reservation in px, or px per breakpoint. Use true for the default 48px reservation. */
+    topInset?: number | boolean | ResponsiveInset;
+    /** Bottom chrome reservation in px, or px per breakpoint. Use true for the default 48px reservation. */
+    bottomInset?: number | boolean | ResponsiveInset;
     gesture?: boolean;
     cache?: boolean;
     /** Initial full-document SSR strategy. Defaults to `"stream"`. */
@@ -39,6 +48,16 @@ export interface CsrState {
     bottomSafeArea: number;
     topInset: number;
     bottomInset: number;
+    /** The declared per-breakpoint insets; `topInset`/`bottomInset` hold their value at the width they resolved at. */
+    responsiveInset?: {
+        top: ResponsiveInset;
+        bottom: ResponsiveInset;
+    };
+    /** Web only: the sides whose safe area `env(safe-area-inset-*)` measures, since a browser tells script nothing. */
+    safeAreaEnv?: {
+        top: boolean;
+        bottom: boolean;
+    };
     gesture: boolean;
     cache: boolean;
     ssr: SsrRenderMode;
@@ -111,13 +130,29 @@ export interface RouteRender {
     resolveNotFound?: () => PromiseOrObject<LayoutNotFoundRender | undefined>;
     resolveError?: () => PromiseOrObject<LayoutErrorRender | undefined>;
     resolveHead?: ResolveHead;
+    /** Parses the declared args without rendering, so a path value the type refuses answers not-found before any byte. */
+    checkArgs?: (props: PageProps) => Promise<void>;
     getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
     getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
     /** A root layout's `theme`, readable before it renders. */
     getLayoutTheme?: () => PromiseOrObject<string | undefined>;
+    /** A root layout's `viewport`, readable before it renders: the document shell writes it ahead of the body. */
+    getLayoutViewport?: () => PromiseOrObject<RouteViewport | undefined>;
+    /** A root layout's `manifest`, which the server answers at the URL its documents link. */
+    getLayoutManifest?: () => PromiseOrObject<WebAppManifest | undefined>;
     /** The `page()` chain behind a page render, when it was declared as one — what a page prompt is read off. */
     getRouteDefinition?: () => PromiseOrObject<RouteDefinition | undefined>;
 }
+export interface RouteViewport {
+    /** `viewport-fit=cover`: the page runs under the notch and home indicator, and `env(safe-area-inset-*)` measures them. */
+    fitCover?: boolean;
+    /** What the on-screen keyboard resizes; `resizes-content` shrinks the layout viewport, and `dvh` with it. */
+    interactiveWidget?: "resizes-visual" | "resizes-content" | "overlays-content";
+    /** The browser chrome's color: one for every theme, or one per theme name the app switches between. */
+    themeColor?: string | {
+        [theme: string]: string;
+    };
+}
 export interface WebAppManifestIcon {
     src: string;
     sizes?: string;
@@ -161,6 +196,7 @@ export interface LayoutModule {
     reconnect?: boolean;
     wsConnect?: boolean;
     layoutStyle?: "mobile" | "web";
+    viewport?: RouteViewport;
     Loading?: LayoutLoadingRender;
     NotFound?: LayoutNotFoundRender;
     Error?: LayoutErrorRender;

package/types/client/frameConfig.d.ts

@@ -1,4 +1,4 @@
-import type { PageConfig, PageState } from "./csrTypes.d.ts";
+import type { PageConfig, PageState, ResponsiveInset } from "./csrTypes.d.ts";
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
 export type SafeAreaInsets = {
     top: number;
@@ -11,10 +11,22 @@ export interface ResolvePageStateOptions {
     platform: DevicePlatform;
     deviceSafeArea: SafeAreaInsets;
     cssSafeArea?: SafeAreaInsets;
+    /** The viewport width in px a responsive inset resolves at; left out, it resolves at `base`. */
+    width?: number;
 }
+/** Tailwind's default breakpoints in rem, the widths a `ResponsiveInset` keys on. */
+export declare const insetBreakpoints: readonly [readonly ["sm", 40], readonly ["md", 48], readonly ["lg", 64], readonly ["xl", 80], readonly ["2xl", 96]];
+export type InsetBreakpoint = "base" | (typeof insetBreakpoints)[number][0];
 export declare function validatePageConfig(routeKey: string, config?: PageConfig): void;
+export declare const isResponsiveInset: (inset: PageConfig["topInset"]) => inset is ResponsiveInset;
+/** The inset at each breakpoint, each one the nearest declared value at or below it. */
+export declare function insetsByBreakpoint(inset: PageConfig["topInset"]): {
+    [bp in InsetBreakpoint]: number;
+};
+/** The inset in force at `width` px, assuming a 16px rem. */
+export declare function insetAt(inset: PageConfig["topInset"], width?: number): number;
 export declare function mergePageConfigs(configChain?: PageConfig[]): PageConfig;
 export declare function getExplicitPageConfigKeys(configChain?: PageConfig[]): Partial<Record<keyof PageConfig, boolean>>;
 export declare const defaultPageState: PageState;
-export declare function resolvePageState({ configChain, path, basePath, platform, deviceSafeArea, cssSafeArea, }: ResolvePageStateOptions): PageState;
+export declare function resolvePageState({ configChain, path, basePath, platform, deviceSafeArea, cssSafeArea, width, }: ResolvePageStateOptions): PageState;
 export declare function readCssSafeAreaInsets(): SafeAreaInsets;

package/types/client/index.d.ts

@@ -2,6 +2,7 @@ export * from "./clientRuntime.d.ts";
 export * from "./cn.d.ts";
 export * from "./cookie.d.ts";
 export * from "./createFont.d.ts";
+export * from "./csrLocation.d.ts";
 export * from "./csrTypes.d.ts";
 export * from "./decorators.d.ts";
 export * from "./device.d.ts";
@@ -17,3 +18,5 @@ export * from "./storage.d.ts";
 export * from "./translator.d.ts";
 export * from "./types.d.ts";
 export * from "./useClient.d.ts";
+export * from "./viewportMeta.d.ts";
+export * from "./webManifest.d.ts";

package/types/client/native/external-view.d.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/external-view/src/index.d.ts";

package/types/client/route/RootLayoutDefinition.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutModule, PageModule, WebAppManifest } from "../csrTypes.d.ts";
+import type { LayoutModule, PageModule, RouteViewport, WebAppManifest } from "../csrTypes.d.ts";
 import type { ReactFont } from "../types.d.ts";
 import { LayoutDefinition } from "./LayoutDefinition.d.ts";
 import type { RouteArgsShape, RouteKind } from "./RouteDefinition.d.ts";
@@ -12,5 +12,6 @@ export declare class RootLayoutDefinition<Args extends RouteArgsShape = Record<n
     reconnect(on?: boolean): this;
     wsConnect(on?: boolean): this;
     layoutStyle(style: "mobile" | "web"): this;
+    viewport(viewport: RouteViewport): this;
     protected extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule;
 }

package/types/client/route/RouteHead.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+import type { ResolveHeadResult } from "../csrTypes.d.ts";
+type TagProps = Record<string, unknown>;
+/** Merges the `.head()` of every route level, root first: a deeper level takes over each singleton tag it writes. */
+export declare class RouteHead {
+    #private;
+    static merge(levels: ResolveHeadResult[]): ResolveHeadResult;
+    /** What makes two tags the same tag; `null` for one that never replaces another. */
+    static keyOf(tag: string, props: TagProps): string | null;
+    /** `merge` for plain JSX heads, root first. */
+    static mergeNodes(nodes: ReactNode[]): ReactNode;
+}
+export {};

package/types/client/route/index.d.ts

@@ -2,6 +2,7 @@ export * from "./LayoutDefinition.d.ts";
 export * from "./PageDefinition.d.ts";
 export * from "./RootLayoutDefinition.d.ts";
 export * from "./RouteDefinition.d.ts";
+export * from "./RouteHead.d.ts";
 export * from "./resolveRouteModule.d.ts";
 export * from "./routeArgs.d.ts";
 export * from "./routeBuilders.d.ts";

package/types/client/router.d.ts

@@ -1,5 +1,11 @@
 export interface RouteOptions {
     scrollToTop?: boolean;
+    /**
+     * Writes the URL and the store's path and search params without asking the server for the page, as for `?peek=`;
+     * honoured only when the path stays the same. A server component reading `.search()` sees it at the next full
+     * navigation.
+     */
+    shallow?: boolean;
 }
 export interface RouteManifest {
     routes: string[];

package/types/client/rscNavigation.d.ts

@@ -7,6 +7,8 @@ declare global {
     var __AKAN_RSC_NAVIGATE__: ((href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;
+        shallow?: boolean;
+        pop?: boolean;
     }) => Promise<void>) | undefined;
     var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
     var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
@@ -18,6 +20,7 @@ export declare const isRscNavigationFromCache: () => boolean;
 export declare const navigateRsc: (href: string, options?: {
     replace?: boolean;
     scrollToTop?: boolean;
+    shallow?: boolean;
 }) => Promise<void> | undefined;
 export declare const refreshRsc: () => Promise<void> | undefined;
 export declare const useRscNavigation: () => {
@@ -26,5 +29,6 @@ export declare const useRscNavigation: () => {
     navigate: (href: string, options?: {
         replace?: boolean;
         scrollToTop?: boolean;
+        shallow?: boolean;
     }) => Promise<void> | undefined;
 };

package/types/client/viewportMeta.d.ts

@@ -0,0 +1,18 @@
+import type { RouteViewport } from "./csrTypes.d.ts";
+export interface ThemeColorTag {
+    content: string;
+    media?: string;
+}
+/** Turns a root layout's `.viewport()` into the `viewport` and `theme-color` meta tags every document shell writes. */
+export declare class ViewportMeta {
+    #private;
+    static content(viewport: RouteViewport | undefined, { native }?: {
+        native?: boolean;
+    }): string;
+    /** The request's theme when it is known; otherwise `light`/`dark` follow the OS until the client names the theme. */
+    static themeColors(viewport: RouteViewport | undefined, theme?: string): ThemeColorTag[];
+    static applyContent(viewport: RouteViewport | undefined, { native }?: {
+        native?: boolean;
+    }): void;
+    static applyThemeColor(viewport: RouteViewport | undefined, theme?: string): void;
+}

package/types/client/webManifest.d.ts

@@ -0,0 +1,4 @@
+/** Where an SSR document links its root layout's `.manifest()`; the server answers it from that layout. */
+export declare const webManifestHref: (basePath?: string | null) => string;
+/** A `.manifest()` object in the browser's own snake_case keys, at every depth. */
+export declare const toManifestJson: (value: unknown) => unknown;

package/types/common/PipelineNames.d.ts

@@ -0,0 +1,6 @@
+export declare class PipelineNames {
+    static isReservedEnv(name: string): boolean;
+    static idError(id: string): string | null;
+    static secretNameError(name: string): string | null;
+    static envNameError(name: string): string | null;
+}

package/types/common/PipelinePattern.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one glob dialect of `when`, shared by the planner (`branch`, `app`) and the executor (`changed`) so both decide
+ * alike. `*` is any run without `/`, `**` any run including `/` (and with its `/` also no segment at all), `?` one
+ * character but `/`; everything else is literal and case-sensitive. A leading `!` excludes.
+ */
+export declare class PipelinePattern {
+    #private;
+    /** True when some positive pattern matches (or none is given) and no `!` pattern does. */
+    static matches(pattern: string | readonly string[], value: string): boolean;
+    /** `changed`: true when at least one of `values` matches. */
+    static matchesAny(pattern: string | readonly string[], values: readonly string[]): boolean;
+    /** Braces and character classes are refused rather than given a meaning, so no implementation can read them apart. */
+    static validate(pattern: string | readonly string[]): string | null;
+}

package/types/common/PipelinePlanSchema.d.ts

@@ -0,0 +1,9 @@
+import { type PipelinePlan, type PipelinePlanResult } from "./pipelinePlan.d.ts";
+/** Strict: an unknown key, kind, action or version is refused, never ignored. Structure only, no executor policy. */
+export declare class PipelinePlanSchema {
+    #private;
+    /** What an executor reads off `--out`: the size is checked before the text is parsed. */
+    static parseText(text: string): PipelinePlanResult;
+    static parseResult(value: unknown): PipelinePlanResult;
+    static parse(value: unknown): PipelinePlan;
+}

package/types/common/backoff.d.ts

@@ -0,0 +1,10 @@
+export interface BackoffPolicy {
+    /** The first wait in ms; each attempt in a row doubles it. */
+    min?: number;
+    max?: number;
+    /** The share of each wait drawn at random, 0 to 1, so callers one outage dropped together come back apart. */
+    jitter?: number;
+}
+export declare class Backoff {
+    static delay(attempt: number, { min, max, jitter }?: BackoffPolicy): number;
+}

package/types/common/index.d.ts

@@ -1,5 +1,6 @@
 export { applyMixins, getAllPropertyDescriptors } from "./applyMixins.d.ts";
 export { authTokenKey, cookieHeaderHasAuthToken, isAuthTokenKey, isOwnAuthToken, legacyAuthTokenKey, readAuthToken, } from "./authToken.d.ts";
+export { Backoff, type BackoffPolicy } from "./backoff.d.ts";
 export { CodeAgentClient, type CodeAgentTransport } from "./CodeAgentClient.d.ts";
 export { CodeTranscript, type CodeTranscriptPart } from "./CodeTranscript.d.ts";
 export { capitalize, lowerlize } from "./capitalize.d.ts";
@@ -28,7 +29,11 @@ export { type Align, MarkdownTable, type TableBlock } from "./markdownTable.d.ts
 export { isMcpDescribableArg, type McpExposureEndpoint, type McpExposureOption, mcpBaseVerbOf, mcpHintsOf, mcpRefusalOf, } from "./mcpExposure.d.ts";
 export { deepObjectify, objectify, plainFieldsOf } from "./objectify.d.ts";
 export { pathGet, pathGetLoose, pathSet, toPathSegments } from "./objectPath.d.ts";
+export { PipelineNames } from "./PipelineNames.d.ts";
+export { PipelinePattern } from "./PipelinePattern.d.ts";
+export { PipelinePlanSchema } from "./PipelinePlanSchema.d.ts";
 export { formatPhone, isPhoneNumber } from "./phone.d.ts";
+export { type PipelineActionName, type PipelineDiagnostic, type PipelineMilestone, type PipelineOtaPlatform, type PipelinePlan, type PipelinePlanActionStep, type PipelinePlanAppActionStep, type PipelinePlanContext, type PipelinePlanOtaStep, type PipelinePlanPhase, type PipelinePlanPost, type PipelinePlanResult, type PipelinePlanRetry, type PipelinePlanShellStep, type PipelinePlanSlot, type PipelinePlanSource, type PipelinePlanStage, type PipelinePlanStep, type PipelineSkip, type PipelineTrigger, pipelineActionNames, pipelineActions, pipelineEnvNamePattern, pipelineIdPattern, pipelineMilestones, pipelineOtaPlatforms, pipelinePlanLimits, pipelinePlanSlots, pipelinePlanVersion, pipelineReservedEnv, pipelineRuntimeEnv, pipelineSecretNamePattern, pipelineTriggers, } from "./pipelinePlan.d.ts";
 export { type RouteLayer, RouteLayering } from "./RouteLayering.d.ts";
 export { randomPick, randomPicks } from "./randomPick.d.ts";
 export { hostFromRequest, isJsonContentType, originFromRequest } from "./requestOrigin.d.ts";