@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/middleware/hook-receipts.ts

@@ -1,11 +1,14 @@
 /**
  * Durable receipt log for user-defined middleware hooks. Every hook execution
- * emits a {@link HookReceipt}; this log keeps a bounded in-memory ring (the live
- * surface `clio-coder config inspect` reads) and persists it atomically through
- * safeResourceWrite. Writes are throttled so a per-tool-call cadence never turns
- * into per-call disk I/O; `flush()` forces a final write at shutdown.
+ * emits a {@link HookReceipt}; this log keeps a bounded in-memory ring and
+ * persists it atomically through safeResourceWrite. Writes are throttled so a
+ * per-tool-call cadence never turns into per-call disk I/O; `flush()` forces a
+ * final write at shutdown. `clio-coder config inspect` reads the persisted
+ * snapshot back with {@link readPersistedHookReceipts}, since it runs as its
+ * own process and has no access to a running session's in-memory ring.
  */
 
+import { readFileSync } from "node:fs";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
 import type { HookReceipt } from "./hooks.js";
 
@@ -68,3 +71,23 @@ export function createHookReceiptLog(options: HookReceiptLogOptions = {}): HookR
 		},
 	};
 }
+
+/**
+ * Read a log's persisted snapshot back, for a process that never held the
+ * live log (`config inspect` runs as its own invocation). A log that has
+ * never persisted yet reads as empty, not an error.
+ */
+export function readPersistedHookReceipts(persistPath: string): HookReceipt[] {
+	let raw: string;
+	try {
+		raw = readFileSync(persistPath, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const parsed = JSON.parse(raw) as Partial<PersistedReceipts>;
+	if (parsed.version !== 1 || !Array.isArray(parsed.receipts)) {
+		throw new Error(`${persistPath}: unrecognized hook receipt log shape`);
+	}
+	return parsed.receipts;
+}

package/src/domains/middleware/hooks-io.ts

@@ -1,12 +1,19 @@
 /**
- * Filesystem loading for user-defined middleware hooks and the production
- * command runner. Hooks live in dedicated, secrets-free files so they stay out
- * of the strict settings schema:
+ * Loading for user-defined middleware hooks and the production command
+ * runner. Hooks live in dedicated, secrets-free files so they stay out of the
+ * strict settings schema:
  *
  *   - `.clio-coder/hooks.yaml`        committed project hooks (origin "project"),
  *   - `.clio-coder/hooks.local.yaml`  gitignored local hooks (origin "project.local"),
  *   - `<extensionRoot>/hooks.yaml`  hooks shipped by an installed extension.
  *
+ * Project files are read from disk here. Extension declarations are never
+ * read here: they arrive already parsed as a captured source set that the
+ * composition root adapts from the extension snapshot, which captured the
+ * bytes during install-digest verification, so a hooks.yaml rewritten after
+ * verification cannot be admitted until the next generation re-verifies the
+ * tree. Middleware never sees extension-domain types.
+ *
  * Reads are best-effort: a missing file is skipped silently, and a malformed
  * file is reported as an issue without aborting anything.
  */
@@ -26,6 +33,7 @@ import {
 	type UserHookCommandRunner,
 	type UserHookDeclarationBatch,
 	type UserHookLoadResult,
+	type UserHookPackageProvenance,
 	type UserHookSource,
 	userHookToRegistration,
 } from "./hooks.js";
@@ -43,15 +51,27 @@ export interface ReadHookSourcesResult {
 	fileIssues: HookFileIssue[];
 }
 
-export interface ExtensionHookRoot {
-	id: string;
-	rootPath: string;
+/** One package's hook declarations, captured by the supplier from verified bytes. */
+export interface CapturedHookDeclarations {
+	provenance: UserHookPackageProvenance;
+	/** SHA-256 of the captured hooks.yaml bytes. */
+	declarationsDigest: string;
+	/** Parsed declarations, or an empty list when parsing failed. */
+	declarations: unknown;
+	parseError?: string;
+}
+
+/** The captured declarations of one supplier generation. */
+export interface CapturedHookSourceSet {
+	/** 0 for an ephemeral (uncommitted) build. */
+	generation: number;
+	sources: ReadonlyArray<CapturedHookDeclarations>;
 }
 
 export interface ReadHookSourcesOptions {
 	cwd: string;
-	/** Installed extension roots, in dependency order. */
-	extensions?: ReadonlyArray<ExtensionHookRoot>;
+	/** Captured extension declarations; absent means no extension hooks. */
+	capturedSources?: CapturedHookSourceSet;
 }
 
 function readBatch(
@@ -86,14 +106,23 @@ export function readHookSources(options: ReadHookSourcesOptions): ReadHookSource
 	const fileIssues: HookFileIssue[] = [];
 	const batches: UserHookDeclarationBatch[] = [];
 
-	for (const extension of options.extensions ?? []) {
+	const captured = options.capturedSources;
+	for (const entry of captured?.sources ?? []) {
 		const source: UserHookSource = {
 			origin: "extension",
-			sourcePath: `${extension.id}:hooks.yaml`,
-			sourceId: extension.id,
+			sourcePath: `${entry.provenance.id}:hooks.yaml`,
+			sourceId: entry.provenance.id,
+			extension: {
+				provenance: entry.provenance,
+				generation: captured?.generation ?? 0,
+				declarationsDigest: entry.declarationsDigest,
+			},
 		};
-		const batch = readBatch(source, join(extension.rootPath, "hooks.yaml"), fileIssues);
-		if (batch) batches.push(batch);
+		if (entry.parseError !== undefined) {
+			fileIssues.push({ source, message: `failed to parse ${source.sourcePath}: ${entry.parseError}` });
+			continue;
+		}
+		batches.push({ source, declarations: entry.declarations });
 	}
 
 	const projectBatch = readBatch(
@@ -113,44 +142,48 @@ export function readHookSources(options: ReadHookSourcesOptions): ReadHookSource
 	return { batches, fileIssues };
 }
 
-export interface InstallUserHooksOptions {
+export interface BuildUserHookRegistrationsOptions {
 	cwd: string;
 	/** Absolute workspace root a command `cwd` must resolve under; defaults to `cwd`. */
 	workspaceRoot?: string;
-	extensions?: ReadonlyArray<ExtensionHookRoot>;
-	registerHook: (registration: MiddlewareHookRegistration) => void;
+	capturedSources?: CapturedHookSourceSet;
 	recordReceipt: HookReceiptSink;
 	/** Injected for tests; defaults to the spawnSync runner. */
 	runCommand?: UserHookCommandRunner;
 	now?: () => number;
 }
 
-export interface InstallUserHooksResult extends UserHookLoadResult {
+export interface BuildUserHookRegistrationsResult extends UserHookLoadResult {
 	fileIssues: HookFileIssue[];
+	/** One registration per admitted hook, in merged precedence order. Nothing is registered here. */
+	registrations: MiddlewareHookRegistration[];
 }
 
 /**
- * Read, normalize, and register every user hook on the middleware contract. The
- * returned hooks and issues feed `clio-coder config inspect`. Best-effort throughout:
- * a malformed file or hook is reported, never thrown.
+ * Read project files, merge them with the captured extension declarations,
+ * normalize, and build one registration per admitted hook. Pure with respect
+ * to the middleware contract: the caller decides when the set is published,
+ * which is what lets extension and hook state publish on one stack. The
+ * returned hooks and issues feed `clio-coder config inspect`. Best-effort
+ * throughout: a malformed file or hook is reported, never thrown.
  */
-export function installUserHooks(options: InstallUserHooksOptions): InstallUserHooksResult {
+export function buildUserHookRegistrations(
+	options: BuildUserHookRegistrationsOptions,
+): BuildUserHookRegistrationsResult {
 	const workspaceRoot = options.workspaceRoot ?? options.cwd;
 	const readOptions: ReadHookSourcesOptions = { cwd: options.cwd };
-	if (options.extensions !== undefined) readOptions.extensions = options.extensions;
+	if (options.capturedSources !== undefined) readOptions.capturedSources = options.capturedSources;
 	const { batches, fileIssues } = readHookSources(readOptions);
 	const loaded = loadUserHooks(batches, { workspaceRoot });
 	const runCommand = options.runCommand ?? spawnSyncCommandRunner();
-	for (const hook of loaded.hooks) {
-		options.registerHook(
-			userHookToRegistration(hook, {
-				recordReceipt: options.recordReceipt,
-				runCommand,
-				...(options.now !== undefined ? { now: options.now } : {}),
-			}),
-		);
-	}
-	return { ...loaded, fileIssues };
+	const registrations = loaded.hooks.map((hook) =>
+		userHookToRegistration(hook, {
+			recordReceipt: options.recordReceipt,
+			runCommand,
+			...(options.now !== undefined ? { now: options.now } : {}),
+		}),
+	);
+	return { ...loaded, fileIssues, registrations };
 }
 
 /**

package/src/domains/middleware/hooks.ts

@@ -51,12 +51,47 @@ export const USER_HOOK_COMMAND_OUTPUT_MAX_CHARS = 4_000;
 /** Cap on a prompt hook's injected message, in characters. */
 export const USER_HOOK_PROMPT_MAX_CHARS = 2_000;
 
+/**
+ * Provenance of an installed package that supplied hook declarations, as the
+ * composition root attributes it. Middleware treats it as opaque identity
+ * data; it neither reads packages nor knows how the digests were produced.
+ */
+export interface UserHookPackageProvenance {
+	id: string;
+	/** Install scope label of the package (for example "user" or "project"). */
+	scope: string;
+	/** Path recorded at install, when known. */
+	sourcePath?: string;
+	/** Canonical filesystem identity of the installed package root. */
+	canonicalRoot: string;
+	/** SHA-256 of the manifest bytes covered by the installed-tree digest. */
+	manifestDigest: string;
+	/** Installed-tree digest recorded at install and reverified by the supplier. */
+	contentDigest: string;
+}
+
+/**
+ * Attribution for a hook declared by an installed package. The declaration
+ * bytes behind `declarationsDigest` are the ones the supplier hashed during
+ * content verification and captured; nothing here was re-read from a mutable
+ * path after verification.
+ */
+export interface UserHookExtensionSource {
+	provenance: UserHookPackageProvenance;
+	/** Generation the declarations were admitted under; 0 for an ephemeral build. */
+	generation: number;
+	/** SHA-256 of the captured hooks.yaml bytes. */
+	declarationsDigest: string;
+}
+
 export interface UserHookSource {
 	origin: UserHookOrigin;
 	/** File path or `extensionId:path` the declaration was read from. */
 	sourcePath: string;
 	/** Extension id when origin is "extension". */
 	sourceId?: string;
+	/** Present exactly when origin is "extension". */
+	extension?: UserHookExtensionSource;
 }
 
 export interface NormalizedCommandHook {
@@ -314,6 +349,17 @@ export function loadUserHooks(
 
 export type UserHookOutcome = "emitted" | "command-ok" | "command-failed" | "command-timeout" | "skipped";
 
+/** Bounded extension attribution carried on every receipt of an extension hook. */
+export interface HookReceiptExtension {
+	id: string;
+	scope: string;
+	canonicalRoot: string;
+	manifestDigest: string;
+	contentDigest: string;
+	declarationsDigest: string;
+	generation: number;
+}
+
 export interface HookReceipt {
 	at: number;
 	hookId: string;
@@ -327,6 +373,7 @@ export interface HookReceipt {
 	exitCode?: number;
 	outputChars?: number;
 	toolName?: string;
+	extension?: HookReceiptExtension;
 }
 
 export type HookReceiptSink = (receipt: HookReceipt) => void;
@@ -372,6 +419,10 @@ export function userHookToRegistration(
 	deps: UserHookRegistrationDeps,
 ): MiddlewareHookRegistration {
 	const now = deps.now ?? Date.now;
+	// Attribution is fixed when the registration is built, so a receipt written
+	// by a registration from an older generation names that generation even
+	// after a newer one is active.
+	const extension = hook.source.extension === undefined ? undefined : receiptExtension(hook.source.extension);
 	const baseReceipt = (input: { toolName?: string }): Omit<HookReceipt, "outcome"> => ({
 		at: now(),
 		hookId: hook.id,
@@ -380,6 +431,7 @@ export function userHookToRegistration(
 		hash: hook.hash,
 		hook: hook.on,
 		kind: hook.spec.kind,
+		...(extension !== undefined ? { extension: { ...extension } } : {}),
 		...(input.toolName !== undefined ? { toolName: input.toolName } : {}),
 	});
 	const registration: MiddlewareHookRegistration = {
@@ -401,6 +453,18 @@ export function userHookToRegistration(
 	return registration;
 }
 
+function receiptExtension(source: UserHookExtensionSource): HookReceiptExtension {
+	return {
+		id: source.provenance.id,
+		scope: source.provenance.scope,
+		canonicalRoot: source.provenance.canonicalRoot,
+		manifestDigest: source.provenance.manifestDigest,
+		contentDigest: source.provenance.contentDigest,
+		declarationsDigest: source.declarationsDigest,
+		generation: source.generation,
+	};
+}
+
 function evaluateHook(
 	hook: NormalizedUserHook,
 	deps: UserHookRegistrationDeps,

package/src/domains/middleware/index.ts

@@ -41,19 +41,27 @@ export {
 } from "./dispatch-nudge.js";
 export type { MiddlewareBundleOptions } from "./extension.js";
 export { createEnvHookBudgetTracker, createMiddlewareBundle } from "./extension.js";
-export { createHookReceiptLog, HOOK_RECEIPT_LOG_CAPACITY, type HookReceiptLog } from "./hook-receipts.js";
+export {
+	createHookReceiptLog,
+	HOOK_RECEIPT_LOG_CAPACITY,
+	type HookReceiptLog,
+	readPersistedHookReceipts,
+} from "./hook-receipts.js";
 export type {
 	HookReceipt,
+	HookReceiptExtension,
 	HookReceiptSink,
 	NormalizedUserHook,
 	UserHookCommandResult,
 	UserHookCommandRunner,
 	UserHookDeclarationBatch,
+	UserHookExtensionSource,
 	UserHookKind,
 	UserHookLoadIssue,
 	UserHookLoadResult,
 	UserHookOrigin,
 	UserHookOutcome,
+	UserHookPackageProvenance,
 	UserHookSource,
 } from "./hooks.js";
 export {
@@ -66,14 +74,23 @@ export {
 	userHookToRegistration,
 } from "./hooks.js";
 export {
-	type ExtensionHookRoot,
+	type BuildUserHookRegistrationsOptions,
+	type BuildUserHookRegistrationsResult,
+	buildUserHookRegistrations,
+	type CapturedHookDeclarations,
+	type CapturedHookSourceSet,
 	type HookFileIssue,
-	type InstallUserHooksResult,
-	installUserHooks,
 	readHookSources,
 	spawnSyncCommandRunner,
 } from "./hooks-io.js";
 export { MiddlewareManifest } from "./manifest.js";
+export {
+	createMarketplaceOfferRegistration,
+	MARKETPLACE_OFFER_REGISTRATION_ID,
+	type MarketplaceOfferDeps,
+	marketplaceAutoInstallReminder,
+	marketplaceOfferReminder,
+} from "./marketplace-offer.js";
 export {
 	createMemoryInterventionRegistration,
 	MEMORY_INTERVENTION_DEFAULT_MAX_TOKENS,
@@ -82,6 +99,19 @@ export {
 	type MemoryInterventionDeps,
 } from "./memory-intervention.js";
 export { announceMemoryStepEndpoint, type MemoryStepEndpointAnnouncerDeps } from "./memory-step-endpoint.js";
+export {
+	createMiddlewareRegistrationTable,
+	MIDDLEWARE_REGISTRATION_OWNERS,
+	type MiddlewareRegistrationConflict,
+	type MiddlewareRegistrationConflictTier,
+	type MiddlewareRegistrationOwner,
+	type MiddlewareRegistrationReplacement,
+	type MiddlewareRegistrationTable,
+	type MiddlewareRegistrationTableOptions,
+	type PrepareRegistrationReplacementResult,
+	type ReplaceRegistrationsRejection,
+	type ReplaceRegistrationsReport,
+} from "./registrations.js";
 export { BUILTIN_MIDDLEWARE_RULE_IDS, listMiddlewareRuleDefinitions, listMiddlewareRules } from "./rules.js";
 export type {
 	MiddlewareDiagnostic,
@@ -92,6 +122,7 @@ export type {
 	RunMiddlewareRegistrationsOptions,
 } from "./runtime.js";
 export {
+	formatRegistrationConflict,
 	registrationFromRuleDefinition,
 	runMiddlewareHook,
 	runMiddlewareRegistrations,