@xlaunch/invariants 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Portions Copyright (c) 2026 Northlatch Labs LLC
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+---
+description: "Runtime invariant checks for live compositions: the registry service that runs package-owned checks, for users and maintainers choosing, configuring, or debugging them."
+kind: "package-reference"
+---
+
+# @xlaunch/invariants
+
+## Summary
+
+`xlaunch-invariants` runs package-owned runtime checks — invariants — inside a Xlaunch composition: any package can ship a `./invariant` companion that verifies its own durable relationships (authoritative event streams and mutable snapshots) while the composition runs. Checks run automatically, and a failed check reports an `InvariantError` attributed to the package that owns the violated relationship. Choose it for compositions that want self-checking diagnostics with a global switch and package-name filters; the standard agent composition already mounts it with the four core companions, and loading the service alone installs no checks.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the registry when a composition should verify its own runtime contracts, then decide which packages' checks run. The service exposes `ctx.invariants`; companions register checks under their package's exact npm name, and every failure carries the owning package name.
+
+### When to use it
+
+Use the registry for compositions that want live diagnostics. [`xlaunch-sdk-minimal`](../../bundle/sdk-minimal/README.md) mounts it with the four core stateful companions — `xlaunch-session`, `xlaunch-agent`, `xlaunch-scope`, and `xlaunch-agent-loop`; `xlaunch-base` deliberately omits runtime diagnostics. Custom compositions mount the registry and add companions for any other loaded package whose contracts they want checked. Loading the registry alone installs no checks: it ships no product checks of its own, so a composition that never mounts a companion observes no diagnostic behavior.
+
+### Enabling checks and selecting packages
+
+The registry is enabled by default and checks every registered package unless filters say otherwise. Use `enabled` as a global switch, `package_allowlist` to admit only named packages, and `package_blocklist` to exclude packages after allowlist matching — a blocklist match overrides an allowlist match. Patterns are case-sensitive JavaScript regular-expression sources (unanchored unless they supply `^` and `$`), and an invalid, blank, or duplicate entry fails service startup instead of being skipped.
+
+```yaml
+- name: '@xlaunch/invariants'
+  config:
+    enabled: true
+    package_allowlist:
+      - '^@xlaunch/'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Global switch for all registered checks |
+| `package_allowlist` | `[]` | Regex sources admitting package names; empty admits all |
+| `package_blocklist` | `[]` | Regex sources excluding package names after allowlist matching |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#xlaunchinvariants) is the exhaustive source for every accepted field and its JSDoc.
+
+### Which checks run
+
+Each companion protects relationships its package owns, and a companion installs a check only for an observable event or mutable-data relationship — never for a service or method presence. The shipped executable companions cover:
+
+| Companion | Checks |
+|---|---|
+| `xlaunch-session`, `xlaunch-agent`, `xlaunch-scope`, `xlaunch-agent-loop` | Session log enclosure and call/result trace, agent-status transitions, scope-filtered dispatch subjects, loop-built request reconstruction |
+| `xlaunch-llm`, `xlaunch-llm-retry`, `xlaunch-tools`, `xlaunch-system-prompt` | LLM stream grammar, retry-failure shape, tool-pipeline stage pairing and frozen results, prompt-assembly section names |
+| `xlaunch-compaction`, `xlaunch-hook-protocol`, `xlaunch-sandbox-policy` | Compaction stream pairing, hook invocation/result pairing, sandbox mode values |
+| `xlaunch-fs`, `xlaunch-subagent`, `xlaunch-workflow`, `xlaunch-tool-workflow` | Filesystem event identity, subagent provider and start/end pairing, workflow lifecycle identity, workflow record shape |
+| `xlaunch-goal`, `xlaunch-goal-round-driver` | Durable goal-stream folds and reconstructed continuation prompts |
+| `xlaunch-permission-presets`, `xlaunch-user-approval`, `xlaunch-commands` | Preset references to live presets, approval asked/decided pairing, command run/done pairing |
+| `xlaunch-jobs`, `xlaunch-tool-todo`, `xlaunch-time-context` | Job snapshot field relationships, whole-list todo shape, durable clock readings |
+| `xlaunch-credentials`, `xlaunch-settings`, `xlaunch-storage-domain`, `xlaunch-workspace` | Commit events against the live service or memory state, entity-cache mirroring |
+| `xlaunch-agent-presets`, `xlaunch-session-title`, `xlaunch-plan-mode`, `xlaunch-schedule` | Preset mount placement, title source citation, plan-mode payload, schedule stream |
+| `xlaunch-client-hmr`, `xlaunch-client-modules`, `xlaunch-client-runtime` | Browser/node-half stat-watcher lifecycle, boot entry graph, slot mutation versioning |
+
+Every other workspace package omits the companion and states the package-specific reason in its README.
+
+### Adding a companion to a custom composition
+
+A companion is a normal plugin you mount beside the registry. It declares any services it needs and registers under its package's exact npm name; the registry joins its setup before the registration completes.
+
+```ts
+import type { Context } from '@xlaunch/cordis'
+import InvariantRegistry from '@xlaunch/invariants'
+import * as SessionInvariant from '@xlaunch/session/invariant'
+
+declare const ctx: Context
+
+ctx.plugin(InvariantRegistry, { enabled: true })
+ctx.plugin(SessionInvariant)
+```
+
+### When a check fails
+
+A violation throws an `InvariantError` from the context that reported it: it carries the stable code `INVARIANT`, the full npm `packageName` of the owning package, and a message prefixed `invariant violated by "<package>": …`. The failure is therefore attributable to a package without the registry importing any product code. A companion whose installer itself fails is disposed and its registration rolled back, so a broken check cannot leave partial listeners behind.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design behind the registry; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+- **Product-independent registry.** The service imports no session, agent, scope, or agent-loop package and contains none of their checks; companions carry checks next to their owners.
+- **Real relationships, not synthetic assertions.** A companion checks an event-stream or mutable-data relationship its package owns; confirming a method, plugin name, injection, or fixed pure result is a type, load, or unit-test concern, never a runtime invariant.
+- **Registration reserves ownership.** A package name is reserved even when filters keep its installer inactive, so two plugins can never silently claim the same name.
+- **Companion wiring is mechanically enforced.** `pnpm run verify-package-invariants` rejects empty installers, installers that omit or ignore the reporter, wrong registration names, incomplete publication wiring, and stale wiring for omitted companions ([companion-omission note](../../../.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md)).
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, `InvariantRegistry` service, selection, registration, `InvariantError` |
+| — | No runtime invariant companion is published; registration ownership and child lifecycle are the service's mutation boundary itself; observing them from the same registry would only duplicate its implementation. |
+
+### Selection and registration lifecycle
+
+`register(packageName, installer)` reserves the full npm name and returns an effect-scoped disposer. An enabled installer runs in a dedicated child fiber; `installer.inject` declares the services that fiber may access, and synchronous or asynchronous completion is joined before registration succeeds. Failure disposes the child and releases the reservation atomically. The service owns every registration fiber, while the returned disposer also belongs to the companion fiber, so unloading either side removes listeners, trace state, and the reservation — a companion can reload and register the same name again without retained state. Session-backed companions rebuild their baseline from durable events; live-only companions observe operations that begin after reload.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the generated service reference to the decision evidence and the group map.
+
+- [Runtime invariants subsystem](../../../docs/subsystems/invariants.md) — the generated reference for `Config`, the installer, the service, and the companion contract.
+- [Generated configuration catalog](../../../docs/config-catalog.md#xlaunchinvariants) — every accepted config field and its source declaration.
+- [Invariant runtime contracts Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md) — what a runtime invariant may assert and the mechanical gate that enforces companion wiring.
+- [Runtime-diagnostics group map](../../README.md) — adjacent diagnostics packages.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the observer validates requests but never rewrites their context.
+
+#### KV Cache effect
+
+Checks observe assembled requests and durable state without mutating request content, so provider cache reuse is exactly what the underlying composition produces.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the registry is a poor fit or needs operational care. They are current package constraints, not a task backlog.
+
+- **Filters are fixed for the service lifetime** — `enabled`, `package_allowlist`, and `package_blocklist` are compiled once at startup; changing them requires a Cordis plugin reload.
+- **Live-only companions miss pre-reload operations** — a companion that only observes live operations cannot reconstruct operations that began before its own reload; session-backed companions rebuild their baseline from durable events.
+- **Request reconstruction covers loop-built requests only** — the `xlaunch-agent-loop` companion reconstructs requests explicitly built by the loop; direct one-shot LLM calls remain outside that contract even when callers freeze them or attach a session id.
+- **No checks without a companion** — the registry ships no product checks; a composition that mounts the service alone observes nothing.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/lib/index.js

@@ -0,0 +1,123 @@
+import { Service } from "@xlaunch/cordis";
+import z from "@xlaunch/schemastery";
+//#region lib/types/index.js
+/**
+* Configurable registry for package-owned runtime invariant contributions.
+* Every workspace package registers checks from a `./invariant` companion;
+* ordinary package entrypoints stay independent of diagnostics.
+*
+* @module @xlaunch/invariants
+*/
+/** Thrown when a package-owned runtime invariant is violated. */
+var InvariantError = class extends Error {
+	/** Stable machine-readable invariant failure code. */
+	code = "INVARIANT";
+	/** Full npm package name that owns the violated invariant. */
+	packageName;
+	/**
+	* Construct a package-attributed invariant failure.
+	* @param packageName - full npm package name that registered the check.
+	* @param message - violated contract, without the standard error prefix.
+	*/
+	constructor(packageName, message) {
+		super(`invariant violated by "${packageName}": ${message}`);
+		this.name = "InvariantError";
+		this.packageName = packageName;
+	}
+};
+/** Compile and validate one package-filter list. */
+function compilePatterns(field, values) {
+	const seen = /* @__PURE__ */ new Set();
+	return values.map((value) => {
+		if (value.length === 0 || value.trim() !== value) throw new Error(`invariants: ${field} entries must be non-blank and have no surrounding whitespace`);
+		if (seen.has(value)) throw new Error(`invariants: ${field} contains duplicate regex ${JSON.stringify(value)}`);
+		seen.add(value);
+		try {
+			return new RegExp(value);
+		} catch (cause) {
+			throw new Error(`invariants: ${field} contains invalid regex ${JSON.stringify(value)}`, { cause });
+		}
+	});
+}
+/** Package-owned invariant registry with global and regex-based selection. */
+var InvariantRegistry = class extends Service {
+	static Config = z.object({
+		enabled: z.boolean().default(true),
+		package_allowlist: z.array(z.string()).default([]),
+		package_blocklist: z.array(z.string()).default([])
+	});
+	enabled;
+	ownerCtx;
+	packageAllowlist;
+	packageBlocklist;
+	registrations = /* @__PURE__ */ new Set();
+	/**
+	* Create and install the invariant registry.
+	* @param ctx - Cordis context that owns the service.
+	* @param config - global enablement and package-name regex filters.
+	*/
+	constructor(ctx, config = {}) {
+		super(ctx, "invariants");
+		this.ownerCtx = ctx;
+		this.enabled = config.enabled ?? true;
+		this.packageAllowlist = compilePatterns("package_allowlist", config.package_allowlist ?? []);
+		this.packageBlocklist = compilePatterns("package_blocklist", config.package_blocklist ?? []);
+	}
+	/** Return whether one full package name passes the configured filters. */
+	selected(packageName) {
+		if (!this.enabled) return false;
+		if (this.packageAllowlist.length > 0 && !this.packageAllowlist.some((pattern) => pattern.test(packageName))) return false;
+		return !this.packageBlocklist.some((pattern) => pattern.test(packageName));
+	}
+	/**
+	* Register one package's invariant installer. The package name is reserved
+	* even when filtering disables its checks. Enabled installers run in a child
+	* fiber; failure disposes that fiber and releases the reservation.
+	* @param packageName - full npm package name that owns the contribution.
+	* @param installer - listener or startup-check installer for the child context.
+	* @returns an effect-scoped disposer for the registration.
+	*/
+	register(packageName, installer) {
+		if (packageName.length === 0 || packageName.trim() !== packageName || /\s/.test(packageName)) throw new Error("invariants: packageName must be non-blank and contain no whitespace");
+		if (this.registrations.has(packageName)) throw new Error(`invariants: package "${packageName}" is already registered`);
+		const ctx = this.ownerCtx;
+		const registrations = this.registrations;
+		registrations.add(packageName);
+		let registration;
+		try {
+			registration = ctx.effect(async () => {
+				if (!this.selected(packageName)) return () => {
+					registrations.delete(packageName);
+				};
+				const installInvariant = (childCtx) => installer(childCtx, (message) => {
+					throw new InvariantError(packageName, message);
+				});
+				try {
+					const child = ctx.plugin(installer.inject === void 0 ? installInvariant : Object.assign(installInvariant, { inject: installer.inject }));
+					try {
+						await child;
+					} catch (error) {
+						await child.dispose();
+						throw error;
+					}
+					return async () => {
+						try {
+							await child.dispose();
+						} finally {
+							registrations.delete(packageName);
+						}
+					};
+				} catch (error) {
+					registrations.delete(packageName);
+					throw error;
+				}
+			}, `invariants.register(${JSON.stringify(packageName)})`);
+		} catch (error) {
+			registrations.delete(packageName);
+			throw error;
+		}
+		return registration;
+	}
+};
+//#endregion
+export { InvariantError, InvariantRegistry, InvariantRegistry as default };

package/lib/types/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Configurable registry for package-owned runtime invariant contributions.
+ * Every workspace package registers checks from a `./invariant` companion;
+ * ordinary package entrypoints stay independent of diagnostics.
+ *
+ * @module @xlaunch/invariants
+ */
+import { Context, Service } from '@xlaunch/cordis';
+import type { Inject } from '@xlaunch/cordis';
+import type Schema from '@xlaunch/schemastery';
+/** Runtime invariant selection configured on the service plugin. */
+export interface Config {
+    /** Global switch; defaults to `true`. */
+    readonly enabled?: boolean;
+    /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+    readonly package_allowlist?: string[];
+    /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+    readonly package_blocklist?: string[];
+}
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+export type InvariantFailure = (message: string) => never;
+/** Install one package's checks into the registration's child context. */
+export interface InvariantInstaller {
+    /**
+     * Install the package contribution.
+     * @param ctx - child context owned by this invariant registration.
+     * @param fail - reporter bound to the registering package name.
+     * @returns nothing, or a promise settling after asynchronous checks finish.
+     */
+    (ctx: Context, fail: InvariantFailure): void | Promise<void>;
+    /** Services the child installer fiber may access. */
+    readonly inject?: Inject;
+}
+/** Thrown when a package-owned runtime invariant is violated. */
+export declare class InvariantError extends Error {
+    /** Stable machine-readable invariant failure code. */
+    readonly code: "INVARIANT";
+    /** Full npm package name that owns the violated invariant. */
+    readonly packageName: string;
+    /**
+     * Construct a package-attributed invariant failure.
+     * @param packageName - full npm package name that registered the check.
+     * @param message - violated contract, without the standard error prefix.
+     */
+    constructor(packageName: string, message: string);
+}
+declare module '@xlaunch/cordis' {
+    interface Context {
+        invariants: InvariantRegistry;
+    }
+}
+/** Package-owned invariant registry with global and regex-based selection. */
+export declare class InvariantRegistry extends Service {
+    static Config: Schema<Config>;
+    private readonly enabled;
+    private readonly ownerCtx;
+    private readonly packageAllowlist;
+    private readonly packageBlocklist;
+    private readonly registrations;
+    /**
+     * Create and install the invariant registry.
+     * @param ctx - Cordis context that owns the service.
+     * @param config - global enablement and package-name regex filters.
+     */
+    constructor(ctx: Context, config?: Config);
+    /** Return whether one full package name passes the configured filters. */
+    private selected;
+    /**
+     * Register one package's invariant installer. The package name is reserved
+     * even when filtering disables its checks. Enabled installers run in a child
+     * fiber; failure disposes that fiber and releases the reservation.
+     * @param packageName - full npm package name that owns the contribution.
+     * @param installer - listener or startup-check installer for the child context.
+     * @returns an effect-scoped disposer for the registration.
+     */
+    register(packageName: string, installer: InvariantInstaller): () => void;
+}
+export default InvariantRegistry;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xlaunch/invariants",
+  "description": "Registry service for package-owned Xlaunch runtime invariants",
+  "version": "0.2.0-beta.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Northlatch-Labs-LLC/xlaunch-agent.git",
+    "directory": "packages/runtime-diagnostics/invariants"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "author": "Northlatch Labs LLC",
+  "peerDependencies": {
+    "@xlaunch/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@xlaunch/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@xlaunch/cordis": "^4.0.2"
+  }
+}