@dougongjs/core 0.3.0 → 0.5.0

package/README.md

@@ -99,7 +99,7 @@ Node.js ≥ 22; Chrome / Edge 119, Firefox 121 or Safari 17.4 for browsers and W
 - 文档站 / Documentation: https://tangerg.github.io/dougong/
 - 仓库 / Repository: https://github.com/Tangerg/dougong
 
-> 早期开发阶段（0.0.x），当前不承诺向后兼容。
-> Early development (0.0.x); no backward-compatibility promises yet.
+> 早期 0.x 开发阶段，当前不承诺向后兼容。
+> Early 0.x development; no backward-compatibility promises yet.
 
 MIT

package/dist/change-set.d.ts

@@ -24,16 +24,19 @@ export type ChangeOperation = {
     readonly installation: InstallationRecord;
 };
 interface ChangePort {
-    create(plugin: NormalizedPlugin, config: unknown): {
+    readonly create: (plugin: NormalizedPlugin, config: unknown) => {
         readonly record: InstallationRecord;
-        readonly publicInstallation: object;
+        readonly facade: Installation<AnyPlugin>;
     };
-    resolve(installation: object): InstallationRecord;
-    execute(operations: ReadonlyArray<ChangeOperation>): Promise<void>;
-    attach(installation: InstallationRecord): void;
-    discard(installation: InstallationRecord, error: unknown): void;
+    readonly resolve: (installation: object) => InstallationRecord;
+    readonly execute: (operations: ReadonlyArray<ChangeOperation>) => Promise<void>;
+    readonly attach: (installation: InstallationRecord) => void;
+    readonly discard: (installation: InstallationRecord, error: unknown) => void;
 }
+type DraftInstallationFactory = ChangePort["create"];
 export declare function discardChangeSetDraft(draft: ChangeSetDraft, error: unknown): void;
+/** Stages explicit ownership into a shared draft without widening the public ChangeSet API. */
+export declare function stageChangeSetInstallation<Declaration extends AnyPlugin>(draft: ChangeSetDraft, plugin: Declaration, config: unknown, create: DraftInstallationFactory): Installation<Declaration>;
 /**
  * Rich one-shot draft for the canonical mutation path. It owns target
  * uniqueness, Installation authority, sealing and commit idempotency before
@@ -45,6 +48,12 @@ export declare class ChangeSetDraft implements ChangeSet {
     install<Declaration extends AnyPlugin>(plugin: Declaration, ...config: PluginConfigArguments<Declaration>): Installation<Declaration>;
     update<Declaration extends AnyPlugin>(installation: Installation<Declaration>, update: InstallationUpdate<Declaration>): void;
     remove<Declaration extends AnyPlugin>(installation: Installation<Declaration>): void;
+    /**
+     * Commit is idempotent by returning the same promise, so two callers awaiting
+     * one draft get one transaction rather than two. `committing` exists to catch
+     * the reentrant case — an `attach` hook that calls `commit()` again — which
+     * would otherwise submit the operation list twice.
+     */
     commit(): Promise<void>;
 }
 export {};

package/dist/change-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../src/change-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAElF,KAAK,iBAAiB,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACrD;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B,CAAC;AAIN,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;CAAE,GACvE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;CACzC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE3E,UAAU,UAAU;IAClB,MAAM,CACJ,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,GACd;QACD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;QACpC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;KACrC,CAAC;IACF,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAClD,OAAO,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,MAAM,CAAC,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC/C,OAAO,CAAC,YAAY,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjE;AAUD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,QAE1E;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,SAAS;;gBAIlC,IAAI,EAAE,UAAU;IAM5B,OAAO,CAAC,WAAW,SAAS,SAAS,EACnC,MAAM,EAAE,WAAW,EACnB,GAAG,MAAM,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC5C,YAAY,CAAC,WAAW,CAAC;IAQ5B,MAAM,CAAC,WAAW,SAAS,SAAS,EAClC,YAAY,EAAE,YAAY,CAAC,WAAW,CAAC,EACvC,MAAM,EAAE,kBAAkB,CAAC,WAAW,CAAC;IA6BzC,MAAM,CAAC,WAAW,SAAS,SAAS,EAAE,YAAY,EAAE,YAAY,CAAC,WAAW,CAAC;IAK7E,MAAM;CAqEP"}
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../src/change-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAElF,KAAK,iBAAiB,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACrD;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B,CAAC;AAIN,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;CAAE,GACvE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;CACzC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE3E,UAAU,UAAU;IAClB,QAAQ,CAAC,MAAM,EAAE,CACf,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,KACZ;QACH,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;QACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;KAC1C,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9E;AAED,KAAK,wBAAwB,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAwBrD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,QAE1E;AAED,+FAA+F;AAC/F,wBAAgB,0BAA0B,CAAC,WAAW,SAAS,SAAS,EACtE,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,wBAAwB,6BAKjC;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,SAAS;;gBAIlC,IAAI,EAAE,UAAU;IAS5B,OAAO,CAAC,WAAW,SAAS,SAAS,EACnC,MAAM,EAAE,WAAW,EACnB,GAAG,MAAM,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC5C,YAAY,CAAC,WAAW,CAAC;IAkB5B,MAAM,CAAC,WAAW,SAAS,SAAS,EAClC,YAAY,EAAE,YAAY,CAAC,WAAW,CAAC,EACvC,MAAM,EAAE,kBAAkB,CAAC,WAAW,CAAC;IA6BzC,MAAM,CAAC,WAAW,SAAS,SAAS,EAAE,YAAY,EAAE,YAAY,CAAC,WAAW,CAAC;IAK7E;;;;;OAKG;IACH,MAAM;CA4EP"}

package/dist/configuration.d.ts

@@ -1,4 +1,15 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-/** Resolves one Plugin config at the Standard Schema trust boundary. */
+/**
+ * Resolves one Plugin config at the Standard Schema trust boundary.
+ *
+ * The validator is third-party code, so its return value is checked as
+ * untrusted input rather than trusted to match the spec. A validator that
+ * returns a string, or an object with neither `value` nor `issues`, is a bug in
+ * that library — it becomes a `TypeError` naming the Installation rather than an
+ * `undefined` config that fails somewhere inside `setup()`.
+ *
+ * A schema is optional. With none declared, the input passes through untouched:
+ * Core does not invent a validation step the Plugin author did not ask for.
+ */
 export declare function resolvePluginConfig(schema: StandardSchemaV1<unknown, unknown> | undefined, input: unknown, installationId: string): Promise<unknown>;
 //# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,wEAAwE;AACxE,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS,EACtD,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,MAAM,oBA6BvB"}
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS,EACtD,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,MAAM,oBA6BvB"}

package/dist/contract-registry.d.ts

@@ -5,10 +5,10 @@ export declare class ContractRegistry {
     get kinds(): ReadonlyMap<string, ContractKind>;
     assertCompatible(contract: ContractIdentity): void;
     remember(contract: ContractIdentity): void;
-    draft(candidateKinds: ReadonlyMap<string, ContractKind>): ContractRegistryDraft;
+    writer(candidateKinds: ReadonlyMap<string, ContractKind>): ContractRegistryWriter;
     commit(kinds: ReadonlyMap<string, ContractKind>): void;
 }
-export declare class ContractRegistryDraft {
+export declare class ContractRegistryWriter {
     #private;
     constructor(registry: ContractRegistry, candidateKinds: ReadonlyMap<string, ContractKind>);
     remember(contract: ContractIdentity): void;

package/dist/contract-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-registry.d.ts","sourceRoot":"","sources":["../src/contract-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGlE,0EAA0E;AAC1E,qBAAa,gBAAgB;;IAG3B,IAAI,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAE7C;IAED,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB;IAI3C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB;IAInC,KAAK,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAIvD,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;CAIhD;AAYD,qBAAa,qBAAqB;;gBAGpB,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAKzF,QAAQ,CAAC,QAAQ,EAAE,gBAAgB;IAenC,MAAM;IAON,OAAO;CAGR;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,QAAQ,EAAE,gBAAgB,QAGhG"}
+{"version":3,"file":"contract-registry.d.ts","sourceRoot":"","sources":["../src/contract-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAYlE,0EAA0E;AAC1E,qBAAa,gBAAgB;;IAG3B,IAAI,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAE7C;IAED,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB;IAI3C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB;IAInC,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAIxD,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;CAIhD;AAYD,qBAAa,sBAAsB;;gBAGrB,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAKzF,QAAQ,CAAC,QAAQ,EAAE,gBAAgB;IAmBnC,MAAM;IAON,OAAO;CAGR;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,QAAQ,EAAE,gBAAgB,QAGhG"}

package/dist/contracts.d.ts

@@ -1,15 +1,27 @@
 declare const contractBrand: unique symbol;
 declare const contractValueSlot: unique symbol;
 declare const optionalBrand: unique symbol;
+/**
+ * Holds `T` in a covariant and a contravariant position at once, which makes
+ * every Contract invariant in `T`. Without the contravariant half, `Service<Cat>`
+ * would be assignable to `Service<Animal>` and `host.get()` could hand back a
+ * value narrower than the token the caller passed in.
+ */
 interface ContractValueSlot<T> {
     readonly value: T;
     readonly accept: (value: T) => void;
 }
 export type ContractKind = "service" | "extensionPoint" | "event";
+/** The erased half of a token: all a registry needs to key it, with no value type. */
 export interface ContractIdentity {
     readonly id: string;
     readonly kind: ContractKind;
 }
+/**
+ * Nominal marker. A structurally identical `{ id, kind }` literal is not a
+ * Contract, so a token has to come from `service()`, `event()` or
+ * `extensionPoint()` rather than from an object written at the call site.
+ */
 interface ContractBrand {
     readonly [contractBrand]: true;
 }
@@ -29,6 +41,11 @@ export interface ExtensionPoint<T> extends Contract<T, "extensionPoint"> {
 }
 export interface Event<T> extends Contract<T, "event"> {
 }
+/**
+ * `optional()` wraps rather than flags, so the required and optional forms of
+ * one Service stay distinct values. A Plugin cannot weaken a hard dependency by
+ * mutating a shared token.
+ */
 interface OptionalServiceIdentity {
     readonly [optionalBrand]: true;
     readonly kind: "optional";
@@ -38,8 +55,18 @@ export interface OptionalService<T> extends OptionalServiceIdentity {
     readonly service: Service<T>;
     readonly [contractValueSlot]: ContractValueSlot<T>;
 }
+/**
+ * Everything a Plugin may name in `requires`. Events are absent on purpose: an
+ * Event is a transient fact reached through the Lifetime, never something whose
+ * presence the dependency graph can order.
+ */
 export type Requirement = ServiceIdentity | ExtensionPointIdentity | OptionalServiceIdentity;
 export type ContractValue<T> = T extends Contract<infer Value, ContractKind> ? Value : never;
+/**
+ * The brand is compile-time only, so a runtime check can be structural at best.
+ * This validates identity shape, not factory provenance. Declaration
+ * normalization takes an owned identity snapshot of accepted values.
+ */
 export declare function isContract(value: unknown, expected?: ContractKind): value is ContractIdentity;
 export declare function assertContract(value: unknown, expected?: ContractKind): asserts value is ContractIdentity;
 export declare function service<T>(id: string): Service<T>;

package/dist/contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}

package/dist/contribution-store.d.ts

@@ -1,9 +1,15 @@
 import { Requirement } from './contracts';
 import { disposeSymbol, Disposable, Publication, StagedResource } from './resource';
 import { SnapshotView } from './snapshot-view';
+/** A contributed entry the contributor may update or withdraw — nobody else can. */
 export interface Contribution<T> extends Disposable {
     readonly update: (value: T) => void;
 }
+/**
+ * The read side: a keyed map, not a list. Keys are `installationId/key`, so two
+ * Installations contributing under the same local key stay distinct, and a
+ * consumer can tell which Installation an entry came from.
+ */
 export type ContributionView<T> = SnapshotView<ReadonlyMap<string, T>>;
 export type ContributionLeaseKind = "view" | "subscription";
 type ExtensionPointIdentity = Extract<Requirement, {
@@ -22,15 +28,28 @@ declare class ContributionRecord<T> implements StagedResource<Contribution<T>> {
 export declare class ContributionStore<T> {
     #private;
     constructor(invalidate: (store: ContributionStore<unknown>) => void, report: (error: unknown) => void, releaseIfUnused: (store: ContributionStore<unknown>) => void);
-    stage(ownerId: string, key: string, value: T, release: (publication: Publication) => void): ContributionRecord<T>;
+    stage(installationId: string, key: string, value: T, release: (publication: Publication) => void): ContributionRecord<T>;
     view(own: (resource: Disposable, kind: ContributionLeaseKind) => () => void): ContributionView<T>;
-    /** A stable view explicitly owned by the Host for graph-external consumers. */
+    /**
+     * A stable view explicitly owned by the Host for graph-external consumers.
+     *
+     * Application code has no Lifetime to lease a view from, so this one is
+     * retained by the Host instead — which also pins the store open for as long as
+     * the Host lives. That is the trade: `host.contributions()` gives a handle that
+     * never goes stale, at the cost of a store that is no longer self-releasing.
+     */
     hostView(): ContributionView<T>;
     snapshot(): ReadonlyMap<string, T>;
     subscribe(listener: () => void, own: (resource: Disposable, kind: ContributionLeaseKind) => () => void): ContributionSubscription;
     insert(id: string, contribution: ContributionRecord<T>, value: T): void;
     update(id: string, contribution: ContributionRecord<T>, value: T): void;
     removeContribution(id: string, contribution: ContributionRecord<T>, visibility: "staged" | "published"): void;
+    /**
+     * Rebuilds the published snapshot, and does nothing when the result would be
+     * equal by identity per key. A change that adds and removes the same entry —
+     * an Instance restarting with an identical contribution — therefore notifies
+     * nobody, instead of waking every observer to hand them what they already had.
+     */
     publishSnapshot(): void;
 }
 declare class ContributionSubscription implements Disposable {

package/dist/contribution-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contribution-store.d.ts","sourceRoot":"","sources":["../src/contribution-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contribution-store.d.ts","sourceRoot":"","sources":["../src/contribution-store.ts"],"names":[],"mappings":"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"}

package/dist/diagnostics.d.ts

@@ -3,6 +3,11 @@ import { InstallationRecord } from './installation';
 import { LifetimeSnapshot } from './lifetime';
 import { LifecycleStatus } from './lifecycle-status';
 import { SnapshotView } from './snapshot-view';
+/**
+ * `changing` is the reason the read window is closed during a transaction.
+ * `host.get()` only answers while the status is `active`, so a Service lookup
+ * mid-change cannot observe a half-applied plan — it fails instead.
+ */
 export type HostStatus = "idle" | "starting" | "active" | "changing" | "stopping";
 export interface InstallationSnapshot {
     readonly id: string;
@@ -26,11 +31,24 @@ export interface HostSnapshot {
     readonly installations: ReadonlyMap<string, InstallationSnapshot>;
     readonly groups: ReadonlyMap<string, GroupSnapshot>;
 }
-/** Immutable operational read model; never a service locator or control plane. */
+interface HostDiagnosticSource {
+    readonly status: HostStatus;
+    readonly installations: Iterable<InstallationRecord>;
+    readonly groups: Iterable<GroupNode>;
+}
+/**
+ * Immutable operational read model; never a service locator or control plane.
+ *
+ * Everything here is data or another read-only view. There is deliberately no
+ * way back: nothing in a snapshot can install, remove, or reach a live Instance.
+ * `revision` increments on every publish so a consumer can tell "nothing
+ * changed" from "changed back to an equal value".
+ */
 export declare class HostDiagnostics {
     #private;
     readonly view: SnapshotView<HostSnapshot>;
-    constructor(name: string, groups: Iterable<GroupNode>, report: (error: unknown) => void);
-    publish(status: HostStatus, installations: Iterable<InstallationRecord>, groups: Iterable<GroupNode>): void;
+    constructor(name: string, read: () => HostDiagnosticSource, report: (error: unknown) => void);
+    publish(): void;
 }
+export {};
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAElF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAClE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACrD;AAED,kFAAkF;AAClF,qBAAa,eAAe;;IAM1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;gBAE9B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAOvF,OAAO,CACL,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAC3C,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;CAqD9B"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEvE;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAElF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAClE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACrD;AAED,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;;IAK1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;gBAE9B,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,oBAAoB,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAS5F,OAAO;CAmDR"}

package/dist/engine.d.ts

@@ -1,7 +1,13 @@
 import { ExtensionPoint, OptionalService, Service } from './contracts';
 import { InstallationGraph } from './installation-graph';
 import { InstallationRecord } from './installation';
-import { Logger } from './lifetime';
+import { InstanceCoordinatorPort } from './instance-coordinator';
+/**
+ * A rolled-back transition is a returned value, not a thrown error: the Host
+ * still has to settle readiness for everything the attempt touched before the
+ * caller's rejection is raised. Only fail-closed — where no consistent state
+ * could be restored — throws out of `transition()`.
+ */
 export type TransitionOutcome = {
     readonly kind: "committed";
     readonly affected: ReadonlySet<InstallationRecord>;
@@ -10,23 +16,38 @@ export type TransitionOutcome = {
     readonly affected: ReadonlySet<InstallationRecord>;
     readonly error: unknown;
 };
-interface EngineOptions {
-    readonly hostName: string;
-    readonly logger: Logger;
-    readonly isInstalled: (installationId: string) => boolean;
-    readonly report: (error: unknown) => void;
-}
 type ServiceAvailability = "available" | "unavailable";
-/** Owns the committed plan and its commit, rollback and fail-closed transitions. */
+/**
+ * Owns the committed plan and its commit, rollback and fail-closed transitions.
+ *
+ * `#plan` is the single definition of "committed". It is assigned only after an
+ * activation succeeds and cleared whenever no consistent graph exists, so
+ * `hasCommittedPlan` is the honest answer to whether this Host can serve reads —
+ * there is no second flag that could disagree with it.
+ */
 export declare class Engine {
     #private;
-    constructor(options: EngineOptions);
+    constructor(port: InstanceCoordinatorPort);
     get hasCommittedPlan(): boolean;
     get<T>(requirement: Service<T> | OptionalService<T>, availability: ServiceAvailability): T | undefined;
     contributions<T>(token: ExtensionPoint<T>): import('./contribution-store').ContributionView<T>;
     buildPlan(installations: Iterable<InstallationRecord>): InstallationGraph;
     start(plan: InstallationGraph): Promise<void>;
     stop(): Promise<unknown[]>;
+    /**
+     * The whole transaction, in the order the steps have to happen.
+     *
+     * Configs resolve and Contract identities draft *before* anything stops,
+     * because those are the failures that can still be taken back for free — a
+     * schema rejection at this point costs nothing. Once the affected Instances
+     * are down, every remaining failure has a price, and the only question left is
+     * whether the previous state can be restored.
+     *
+     * The whole body runs inside one contribution batch, so contributions
+     * withdrawn by stopping Instances and added by starting ones become visible in
+     * a single step. Without it, an ExtensionPoint observer would see the set
+     * briefly empty in the middle of a successful change.
+     */
     transition(nextPlan: InstallationGraph, changed: ReadonlySet<InstallationRecord>, restoreDeclarations: () => void): Promise<TransitionOutcome>;
 }
 export {};

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAA;CAAE,GAClF;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;AAEN,UAAU,aAAa;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAED,KAAK,mBAAmB,GAAG,WAAW,GAAG,aAAa,CAAC;AAEvD,oFAAoF;AACpF,qBAAa,MAAM;;gBAKL,OAAO,EAAE,aAAa;IAIlC,IAAI,gBAAgB,YAEnB;IAED,GAAG,CAAC,CAAC,EACH,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,EAC5C,YAAY,EAAE,mBAAmB,GAChC,CAAC,GAAG,SAAS;IAoBhB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;IAMzC,SAAS,CAAC,aAAa,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAI/C,KAAK,CAAC,IAAI,EAAE,iBAAiB;IAY7B,IAAI;IAMJ,UAAU,CACd,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,WAAW,CAAC,kBAAkB,CAAC,EACxC,mBAAmB,EAAE,MAAM,IAAI,GAC9B,OAAO,CAAC,iBAAiB,CAAC;CAsI9B"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAA;CAAE,GAClF;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;AAEN,KAAK,mBAAmB,GAAG,WAAW,GAAG,aAAa,CAAC;AAEvD;;;;;;;GAOG;AACH,qBAAa,MAAM;;gBAKL,IAAI,EAAE,uBAAuB;IAIzC,IAAI,gBAAgB,YAEnB;IAED,GAAG,CAAC,CAAC,EACH,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,EAC5C,YAAY,EAAE,mBAAmB,GAChC,CAAC,GAAG,SAAS;IAoBhB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;IAMzC,SAAS,CAAC,aAAa,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAI/C,KAAK,CAAC,IAAI,EAAE,iBAAiB;IAY7B,IAAI;IAQV;;;;;;;;;;;;;OAaG;IACG,UAAU,CACd,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,WAAW,CAAC,kBAAkB,CAAC,EACxC,mBAAmB,EAAE,MAAM,IAAI,GAC9B,OAAO,CAAC,iBAAiB,CAAC;CA0J9B"}

package/dist/errors.d.ts

@@ -1,12 +1,58 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 export declare class DougongError extends Error {
-    readonly code: string;
     name: string;
+    readonly code: string;
     constructor(code: string, message: string, options?: ErrorOptions);
 }
-/** Preserves explicit Error values and classifies non-Error rejection reasons. */
+/** Bounded diagnostic values, with no references to the failed object graph. */
+export interface ErrorSnapshot {
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly stack?: string;
+    readonly cause?: ErrorSnapshot;
+    readonly errors?: ReadonlyArray<ErrorSnapshot>;
+    readonly manifestName?: string;
+    readonly denied?: ReadonlyArray<string>;
+    readonly issues?: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<string | number>;
+    }>;
+    readonly truncated?: true;
+}
+/**
+ * A terminal failure is a record, never a reconstruction of the original class.
+ * Operations still reject with their live error; retained terminal handles use
+ * this class so causes and custom fields cannot retain application resources.
+ */
+export declare class RecordedFailure extends Error {
+    readonly name = "RecordedFailure";
+    readonly code: string | undefined;
+    readonly snapshot: ErrorSnapshot;
+    constructor(error: Error);
+}
+/**
+ * Preserves explicit Error values and classifies non-Error rejection reasons.
+ *
+ * `throw "nope"` in a Plugin must not become an unnamed failure at the Host
+ * boundary, so a non-Error reason is wrapped in a coded Error with the original
+ * kept as `cause`. A real Error is returned untouched — Core never rewrites a
+ * failure a Plugin author deliberately threw.
+ *
+ * The private marker class is why re-normalizing is safe: a wrapper that already
+ * belongs to Core can be re-coded as it passes an outer boundary instead of
+ * being wrapped a second time.
+ */
 export declare function normalizeFailure(error: unknown, code: string, message: string): Error;
-/** Classifies the exact signal reason or a conventional AbortError, but only after abort. */
+/**
+ * Classifies the exact signal reason or a conventional AbortError, but only
+ * after abort.
+ *
+ * This is the one place Core is allowed to stop propagating a failure, so the
+ * test is deliberately narrow. Checking `signal.aborted` first means an
+ * `AbortError` thrown by unrelated code on a live signal stays a real error, and
+ * only a cancellation that this Lifetime actually requested is treated as one.
+ */
 export declare function isCancellationReason(signal: AbortSignal, error: unknown): boolean;
 export declare class ConfigValidationError extends DougongError {
     name: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,qBAAa,YAAa,SAAQ,KAAK;aAInB,IAAI,EAAE,MAAM;IAHrB,IAAI,SAAkB;gBAGb,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIzB;AAKD,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAKrF;AAED,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,WAcvE;AAED,qBAAa,qBAAsB,SAAQ,YAAY;IAC5C,IAAI,SAA2B;IACxC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAE3C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC;CAQ1D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,qBAAa,YAAa,SAAQ,KAAK;IAC5B,IAAI,SAAkB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAQlE;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;QAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;KAChD,CAAC,CAAC;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAqB;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;gBAErB,KAAK,EAAE,KAAK;CAUzB;AAuGD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAKrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,WAcvE;AAED,qBAAa,qBAAsB,SAAQ,YAAY;IAC5C,IAAI,SAA2B;IACxC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBAE3C,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,CAAC;CAQ1D"}

package/dist/event-hub.d.ts

@@ -1,13 +1,24 @@
 import { Disposable, Publication, StagedResource } from './resource';
 export type EventListener<T> = (payload: T) => unknown;
 interface ListenerSlot<T> {
-    readonly listener: EventListener<T>;
+    listener: EventListener<T> | undefined;
 }
 export declare class EventHub {
     #private;
     stage<T>(eventId: string, listener: EventListener<T>, release: (publication: Publication) => void): StagedResource<Disposable>;
     add<T>(eventId: string, slot: ListenerSlot<T>): void;
     delete<T>(eventId: string, slot: ListenerSlot<T>): void;
+    /**
+     * Every still-subscribed listener runs, then failures are aggregated. Three details, all
+     * deliberate:
+     *
+     * - the listener set is copied first; a new subscription does not join this
+     *   emission. A disposed slot is skipped if its callback has not started;
+     * - each call is wrapped in a resolved promise, so a listener that throws
+     *   synchronously is collected like one that rejects;
+     * - `allSettled`, so one broken listener cannot stop the others from being
+     *   told. The emitter still learns about it — every error comes back.
+     */
     emit<T>(eventId: string, payload: T): Promise<void>;
 }
 export {};

package/dist/event-hub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-hub.d.ts","sourceRoot":"","sources":["../src/event-hub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnG,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC;AAEvD,UAAU,YAAY,CAAC,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CACrC;AAqED,qBAAa,QAAQ;;IAGnB,KAAK,CAAC,CAAC,EACL,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,OAAO,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,GAC1C,cAAc,CAAC,UAAU,CAAC;IAK7B,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAM7C,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAO1C,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;CAe1C"}
+{"version":3,"file":"event-hub.d.ts","sourceRoot":"","sources":["../src/event-hub.ts"],"names":[],"mappings":"AAQA,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnG,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC;AAEvD,UAAU,YAAY,CAAC,CAAC;IACtB,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CACxC;AAsED,qBAAa,QAAQ;;IAGnB,KAAK,CAAC,CAAC,EACL,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,OAAO,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,GAC1C,cAAc,CAAC,UAAU,CAAC;IAK7B,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAM7C,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAOhD;;;;;;;;;;OAUG;IACG,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;CAa1C"}

package/dist/group-configuration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * One explicit transaction shared by every nested Group configure callback.
+ *
+ * Nested `group()` calls join the outer session instead of opening their own, so
+ * a whole tree of groups declared in one statement commits once. A failure
+ * anywhere in that tree fails the session, which is why `fail()` records the
+ * first error and later calls return it unchanged: the cause of a collapsed tree
+ * is the first thing that went wrong, not the last.
+ */
+export declare class GroupConfigurationSession<Draft> {
+    #private;
+    constructor(draft: Draft, discard: (draft: Draft, error: unknown) => void, normalize: (error: unknown) => Error);
+    get failure(): Error | undefined;
+    requireDraft(): Draft;
+    assertOpen(): void;
+    fail(error: unknown): Error;
+    seal(): Draft;
+    discard(error: unknown): void;
+}
+//# sourceMappingURL=group-configuration.d.ts.map

package/dist/group-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-configuration.d.ts","sourceRoot":"","sources":["../src/group-configuration.ts"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,qBAAa,yBAAyB,CAAC,KAAK;;gBAIxC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,EAC/C,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK;IAKtC,IAAI,OAAO,sBAEV;IAED,YAAY;IAOZ,UAAU;IAIV,IAAI,CAAC,KAAK,EAAE,OAAO;IAcnB,IAAI;IAQJ,OAAO,CAAC,KAAK,EAAE,OAAO;CAOvB"}

package/dist/group-coordinator.d.ts

@@ -1,24 +1,25 @@
 import { Group, Installation, PluginConfigArguments } from './host-api';
 import { ChangeSetDraft, ChangeOperation } from './change-set';
-import { GroupConfigurationSession, GroupNode } from './group';
+import { GroupNode } from './group';
+import { GroupConfigurationSession } from './group-configuration';
 import { InstallationRecord } from './installation';
 import { LifecycleStatus } from './lifecycle-status';
 import { AnyPlugin, NormalizedPlugin } from './plugin';
 export interface GroupCoordinatorPort {
-    installations(): Iterable<InstallationRecord>;
-    createDraft(group: GroupNode, plugin: NormalizedPlugin, config: unknown): {
+    readonly installations: () => Iterable<InstallationRecord>;
+    readonly createDraft: (group: GroupNode, plugin: NormalizedPlugin, config: unknown) => {
         readonly record: InstallationRecord;
-        readonly publicInstallation: object;
+        readonly facade: Installation<AnyPlugin>;
     };
-    resolveInstallation(installation: object): InstallationRecord;
-    executeChanges(group: GroupNode, operations: ReadonlyArray<ChangeOperation>): Promise<void>;
-    attachInstallation(installation: InstallationRecord): void;
-    discardInstallation(installation: InstallationRecord, error: unknown): void;
-    runExclusive(operation: () => Promise<void>): Promise<void>;
-    removeInstallations(operations: ReadonlyArray<ChangeOperation>): Promise<void>;
-    notifyChanged(): void;
+    readonly resolveInstallation: (installation: object) => InstallationRecord;
+    readonly executeChanges: (group: GroupNode, operations: ReadonlyArray<ChangeOperation>) => Promise<void>;
+    readonly attachInstallation: (installation: InstallationRecord) => void;
+    readonly discardInstallation: (installation: InstallationRecord, error: unknown) => void;
+    readonly runExclusive: (operation: () => Promise<void>) => Promise<void>;
+    readonly removeInstallations: (operations: ReadonlyArray<ChangeOperation>) => Promise<void>;
+    readonly notifyChanged: () => void;
 }
-declare class GroupImpl implements Group {
+declare class GroupFacade implements Group {
     #private;
     constructor(coordinator: GroupCoordinator, node: GroupNode, configuration?: GroupConfigurationSession<ChangeSetDraft>);
     get id(): string;
@@ -27,18 +28,36 @@ declare class GroupImpl implements Group {
     ready(): Promise<void>;
     install<Declaration extends AnyPlugin>(plugin: Declaration, ...config: PluginConfigArguments<Declaration>): Installation<Declaration>;
     change(): ChangeSetDraft;
-    group(name: string, configure: (group: Group) => void): GroupImpl;
+    group(name: string, configure: (group: Group) => void): GroupFacade;
     remove(): Promise<void>;
 }
-/** Owns the complete structural Group model and compiles it to Installation changes. */
+/**
+ * Owns the complete structural Group model and compiles it to Installation
+ * changes.
+ *
+ * Groups are structure, and the Engine only understands installations, so
+ * everything here ends as a `ChangeOperation` list. Removing a Group is not its
+ * own kind of command — it is the removal of every Installation the subtree
+ * contains, followed by detaching the nodes.
+ *
+ * Lifecycles and facades are held in WeakMaps keyed by node rather than as node
+ * fields, so `GroupNode` stays pure structure and a revoked facade releases both.
+ */
 export declare class GroupCoordinator {
     #private;
     readonly root: GroupNode;
     constructor(rootName: string, port: GroupCoordinatorPort);
     nodes(): GroupNode[];
     install<Declaration extends AnyPlugin>(group: GroupNode, plugin: Declaration, ...config: PluginConfigArguments<Declaration>): Installation<Declaration>;
+    stageConfigurationInstall<Declaration extends AnyPlugin>(group: GroupNode, configuration: GroupConfigurationSession<ChangeSetDraft>, plugin: Declaration, ...config: PluginConfigArguments<Declaration>): Installation<Declaration>;
+    /**
+     * `deferred` tracking exists for `create()`. A Group being configured must not
+     * mark itself pending on each nested install, because the whole configuration
+     * commits once; the coordinator attaches that single operation to every node in
+     * the finished subtree instead.
+     */
     change(group: GroupNode, tracking?: "immediate" | "deferred"): ChangeSetDraft;
-    create(parent: GroupNode, name: string, configure: (group: Group) => void, inherited?: GroupConfigurationSession<ChangeSetDraft>): GroupImpl;
+    create(parent: GroupNode, name: string, configure: (group: Group) => void, inherited?: GroupConfigurationSession<ChangeSetDraft>): GroupFacade;
     ready(group: GroupNode): Promise<void>;
     status(group: GroupNode): LifecycleStatus;
     remove(group: GroupNode): Promise<void>;

package/dist/group-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-coordinator.d.ts","sourceRoot":"","sources":["../src/group-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAyB,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE3F,OAAO,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,aAAa,IAAI,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC9C,WAAW,CACT,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,GACd;QAAE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAAC;IAChF,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAC9D,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,kBAAkB,CAAC,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC3D,mBAAmB,CAAC,YAAY,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5E,YAAY,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,mBAAmB,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,aAAa,IAAI,IAAI,CAAC;CACvB;AAkBD,cAAM,SAAU,YAAW,KAAK;;gBAK5B,WAAW,EAAE,gBAAgB,EAC7B,IAAI,EAAE,SAAS,EACf,aAAa,CAAC,EAAE,yBAAyB,CAAC,cAAc,CAAC;IAoB3D,IAAI,EAAE,WAEL;IAED,IAAI,IAAI,WAEP;IAED,IAAI,MAAM,oBAGT;IAED,KAAK;IAOL,OAAO,CAAC,WAAW,SAAS,SAAS,EACnC,MAAM,EAAE,WAAW,EACnB,GAAG,MAAM,EAAE,qBAAqB,CAAC,WAAW,CAAC;IAS/C,MAAM;IAON,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;IAWrD,MAAM;CAaP;AAED,wFAAwF;AACxF,qBAAa,gBAAgB;;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;gBAKb,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB;IASxD,KAAK;IAIL,OAAO,CAAC,WAAW,SAAS,SAAS,EACnC,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,WAAW,EACnB,GAAG,MAAM,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC5C,YAAY,CAAC,WAAW,CAAC;IAO5B,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,GAAE,WAAW,GAAG,UAAwB;IA+BzE,MAAM,CACJ,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EACjC,SAAS,CAAC,EAAE,yBAAyB,CAAC,cAAc,CAAC;IAgDjD,KAAK,CAAC,KAAK,EAAE,SAAS;IAM5B,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,eAAe;IAKzC,MAAM,CAAC,KAAK,EAAE,SAAS;CAkExB"}
+{"version":3,"file":"group-coordinator.d.ts","sourceRoot":"","sources":["../src/group-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/group-lifecycle.d.ts

@@ -12,6 +12,19 @@ export declare class GroupLifecycle {
     constructor(node: GroupNode, initialState: "new" | "established", notifyChanged: () => void);
     status(contents: LifecycleStatus): LifecycleStatus;
     ready(readyContents: () => Promise<void>): Promise<void>;
+    /**
+     * `preserveCommittedState` is the whole point of this class.
+     *
+     * A Group that has already committed something is established, and a later
+     * failed change does not un-establish it — the transaction rolled back, so the
+     * state the Group describes is still the one that was committed. Such a
+     * failure leaves the phase at `established` and does not rethrow, because the
+     * caller of the failed change already has the error.
+     *
+     * A Group whose *first* change fails never had a committed state, so it does
+     * become `failed` and the failure propagates: there is nothing to report but
+     * the failure.
+     */
     track(operation: Promise<void>): void;
     release(): void;
 }

package/dist/group-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-lifecycle.d.ts","sourceRoot":"","sources":["../src/group-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoB,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,cAAc;;IAKvB,QAAQ,CAAC,IAAI,EAAE,SAAS;gBAAf,IAAI,EAAE,SAAS,EACxB,YAAY,EAAE,KAAK,GAAG,aAAa,EACnC,aAAa,EAAE,MAAM,IAAI;IAM3B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe;IAQ5C,KAAK,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAU9C,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC;IAwC9B,OAAO;CASR;AAaD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,gBAEjD"}
+{"version":3,"file":"group-lifecycle.d.ts","sourceRoot":"","sources":["../src/group-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoB,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,cAAc;;IAKvB,QAAQ,CAAC,IAAI,EAAE,SAAS;gBAAf,IAAI,EAAE,SAAS,EACxB,YAAY,EAAE,KAAK,GAAG,aAAa,EACnC,aAAa,EAAE,MAAM,IAAI;IAM3B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe;IAQ5C,KAAK,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAU9C;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC;IAwC9B,OAAO;CASR;AAaD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,gBAEjD"}