@dougongjs/core 0.4.0 → 0.5.0

package/dist/installation-graph.d.ts

@@ -1,5 +1,5 @@
 import { ContractKind } from './contracts';
-import { InstallationRecord } from './installation';
+import { InstallationDeclaration, InstallationRecord } from './installation';
 /** Immutable validated dependency plan over one Host-wide installation graph. */
 export declare class InstallationGraph {
     #private;
@@ -10,8 +10,15 @@ export declare class InstallationGraph {
     readonly contractKinds: ReadonlyMap<string, ContractKind>;
     private constructor();
     static build(source: Iterable<InstallationRecord>, committedKinds: ReadonlyMap<string, ContractKind>): InstallationGraph;
+    declarationFor(installation: InstallationRecord): InstallationDeclaration;
     providerFor(installation: InstallationRecord, serviceId: string): InstallationRecord | undefined;
     provider(serviceId: string): InstallationRecord | undefined;
+    /**
+     * Transitive dependents in *both* plans. A Service being replaced has old
+     * consumers that must stop and new ones that must start, and only the union
+     * covers both — expanding in the current plan alone would leave an Instance
+     * running against a dependency that no longer exists.
+     */
     affectedByTransitionTo(other: InstallationGraph, changed: ReadonlySet<InstallationRecord>): Set<InstallationRecord>;
 }
 //# sourceMappingURL=installation-graph.d.ts.map

package/dist/installation-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installation-graph.d.ts","sourceRoot":"","sources":["../src/installation-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,iFAAiF;AACjF,qBAAa,iBAAiB;;IAO1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,kBAAkB,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;IACrF,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAL3D,OAAO;IAWP,MAAM,CAAC,KAAK,CACV,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAsBnD,WAAW,CAAC,YAAY,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM;IAI/D,QAAQ,CAAC,SAAS,EAAE,MAAM;IAI1B,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,WAAW,CAAC,kBAAkB,CAAC;CAmB1F"}
+{"version":3,"file":"installation-graph.d.ts","sourceRoot":"","sources":["../src/installation-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAWlF,iFAAiF;AACjF,qBAAa,iBAAiB;;IAS1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,kBAAkB,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC;IACrF,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IAN3D,OAAO;IAaP,MAAM,CAAC,KAAK,CACV,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC;IA2BnD,cAAc,CAAC,YAAY,EAAE,kBAAkB;IAM/C,WAAW,CAAC,YAAY,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM;IAI/D,QAAQ,CAAC,SAAS,EAAE,MAAM;IAI1B;;;;;OAKG;IACH,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,WAAW,CAAC,kBAAkB,CAAC;CAmB1F"}

package/dist/installation-registry.d.ts

@@ -27,6 +27,12 @@ export declare class InstallationRegistry {
     };
     resolve(value: object): InstallationRecord;
     attach(installation: InstallationRecord): void;
+    /**
+     * Validates the whole batch, then applies the whole batch. The two loops are
+     * not a style choice: a rejected operation halfway through a single loop would
+     * leave the earlier ones already written, and this method has no way to undo
+     * them. Checking first means `apply` either changes everything or nothing.
+     */
     apply(operations: ReadonlyArray<ChangeOperation>): void;
     settleChanges(operations: ReadonlyArray<ChangeOperation>, active: boolean): void;
     settleReadiness(records: Iterable<InstallationRecord>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"installation-registry.d.ts","sourceRoot":"","sources":["../src/installation-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAEL,KAAK,uBAAuB,EAC5B,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5D,KAAK,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AAC/C,KAAK,qBAAqB,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAE3D,UAAU,wBAAwB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,CACf,YAAY,EAAE,kBAAkB,EAChC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,qBAAqB,KAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/F;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;CAC/C;AAkFD,iFAAiF;AACjF,qBAAa,oBAAoB;;gBAOnB,IAAI,EAAE,wBAAwB;IAI1C,MAAM;IAIN,GAAG,CAAC,EAAE,EAAE,MAAM;IAId,QAAQ,CAAC,YAAY,EAAE,kBAAkB;IAIzC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO;;;;IAiBlE,OAAO,CAAC,KAAK,EAAE,MAAM;IAMrB,MAAM,CAAC,YAAY,EAAE,kBAAkB;IAYvC,KAAK,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC;IA0ChD,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO;IAYzE,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAIrD,OAAO,CAAC,YAAY,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO;IAKxD,OAAO,IAAI,aAAa,CAAC,mBAAmB,CAAC;IAO7C,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC;CAgBrD"}
+{"version":3,"file":"installation-registry.d.ts","sourceRoot":"","sources":["../src/installation-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAEL,KAAK,uBAAuB,EAC5B,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5D,KAAK,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AAC/C,KAAK,qBAAqB,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAE3D,UAAU,wBAAwB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,CACf,YAAY,EAAE,kBAAkB,EAChC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,qBAAqB,KAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/F;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;CAC/C;AAyFD,iFAAiF;AACjF,qBAAa,oBAAoB;;gBAOnB,IAAI,EAAE,wBAAwB;IAI1C,MAAM;IAIN,GAAG,CAAC,EAAE,EAAE,MAAM;IAId,QAAQ,CAAC,YAAY,EAAE,kBAAkB;IAIzC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO;;;;IAiBlE,OAAO,CAAC,KAAK,EAAE,MAAM;IAMrB,MAAM,CAAC,YAAY,EAAE,kBAAkB;IAYvC;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC;IA0ChD,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO;IAYzE,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAIrD,OAAO,CAAC,YAAY,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO;IAQxD,OAAO,IAAI,aAAa,CAAC,mBAAmB,CAAC;IAO7C,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC;CAgBrD"}

package/dist/installation.d.ts

@@ -26,20 +26,38 @@ export declare class InstallationRecord {
     attach(notifyChanged: () => void): void;
     get status(): LifecycleStatus;
     /** Whether the owning ChangeSet has granted this Installation Host authority. */
-    get attached(): boolean;
+    get hasAuthority(): boolean;
     get instance(): Instance | undefined;
-    get error(): TypeError | undefined;
+    get error(): Error | undefined;
     get group(): GroupNode;
     get declaration(): InstallationDeclaration;
     replaceDeclaration(declaration: InstallationDeclaration): void;
     ready(): Promise<void>;
-    unavailableError(): TypeError;
+    unavailableError(): Error;
+    /**
+     * Binds `ready()` to the change currently in flight.
+     *
+     * The `attempt` token is the point: a second change can start before the
+     * first one's promise settles, and only the latest attempt is allowed to clear
+     * the barrier. Without it, a stale resolution would report readiness for an
+     * attempt that has already been superseded.
+     *
+     * A rejection is rethrown only when this Installation did not end up active.
+     * A change that failed elsewhere in the batch but left this one running is not
+     * this Installation's failure to report.
+     */
     trackReadiness(operation: Promise<void>): void;
     activate(instance: Instance): void;
     settleReady(): void;
     beginStopping(): boolean;
     deactivate(): void;
     fail(error: unknown): Error;
+    /**
+     * For an Installation that never made it into the graph. Unlike `fail()`, this
+     * is terminal: readiness settles immediately, the attachment is dropped, and
+     * the reason is kept as a RecordedFailure rather than the live Error. The handle the
+     * caller already holds stays usable and reports why it is dead.
+     */
     discard(error: unknown): void;
     remove(): void;
 }

package/dist/installation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../src/installation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,GACd,uBAAuB,CAEzB;AA2BD;;;;GAIG;AACH,qBAAa,kBAAkB;;IAa3B,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM;IATxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAQd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACtB,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,uBAAuB;IAMtC,MAAM,CAAC,aAAa,EAAE,MAAM,IAAI;IAMhC,IAAI,MAAM,IAAI,eAAe,CAE5B;IAED,iFAAiF;IACjF,IAAI,QAAQ,YAEX;IAED,IAAI,QAAQ,yBAGX;IAED,IAAI,KAAK,0BAWR;IAED,IAAI,KAAK,cAER;IAED,IAAI,WAAW,4BAEd;IAED,kBAAkB,CAAC,WAAW,EAAE,uBAAuB;IAIvD,KAAK;IAML,gBAAgB;IAUhB,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC;IAuCvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAI3B,WAAW;IAkBX,aAAa;IAOb,UAAU;IAIV,IAAI,CAAC,KAAK,EAAE,OAAO;IAInB,OAAO,CAAC,KAAK,EAAE,OAAO;IAuBtB,MAAM;CAwBP"}
+{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../src/installation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,GACd,uBAAuB,CAEzB;AAuBD;;;;GAIG;AACH,qBAAa,kBAAkB;;IAa3B,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM;IATxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAQd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACtB,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,uBAAuB;IAMtC,MAAM,CAAC,aAAa,EAAE,MAAM,IAAI;IAMhC,IAAI,MAAM,IAAI,eAAe,CAE5B;IAED,iFAAiF;IACjF,IAAI,YAAY,YAEf;IAED,IAAI,QAAQ,yBAGX;IAED,IAAI,KAAK,sBASR;IAED,IAAI,KAAK,cAER;IAED,IAAI,WAAW,4BAEd;IAED,kBAAkB,CAAC,WAAW,EAAE,uBAAuB;IAIvD,KAAK;IAML,gBAAgB;IAUhB;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC;IA2CvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAI3B,WAAW;IAkBX,aAAa;IAOb,UAAU;IAIV,IAAI,CAAC,KAAK,EAAE,OAAO;IAInB;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO;IAuBtB,MAAM;CAwBP"}

package/dist/instance-coordinator.d.ts

@@ -1,4 +1,4 @@
-import { ContractRegistryDraft } from './contract-registry';
+import { ContractRegistryWriter } from './contract-registry';
 import { ExtensionPoint } from './contracts';
 import { ContributionView } from './contribution-store';
 import { InstallationGraph } from './installation-graph';
@@ -12,7 +12,19 @@ export interface InstanceCoordinatorPort {
 }
 export declare class IncompleteActivationCleanupError extends AggregateError {
 }
-/** Owns live Instances and the capabilities reachable from their Lifetimes. */
+/**
+ * Owns live Instances and the capabilities reachable from their Lifetimes.
+ *
+ * The only place in Core where `setup()` is called and where a Service value
+ * exists as a value. Above this line everything is declarations and plans; below
+ * it there are running objects.
+ *
+ * Activation is prepare-then-commit, per layer. Every Instance in a layer is
+ * built first, and only once the whole layer succeeds does any of it become
+ * visible. That is why a failing sibling cannot be observed by one that
+ * succeeded, and why cleanup after a failed layer can still reach everything the
+ * layer created.
+ */
 export declare class InstanceCoordinator {
     #private;
     constructor(port: InstanceCoordinatorPort);
@@ -28,8 +40,25 @@ export declare class InstanceCoordinator {
     resetActivationState(): void;
     commitActivationOrder(order: ReadonlyArray<InstallationRecord>): void;
     deactivateAll(): Promise<unknown[]>;
-    activate(plan: InstallationGraph, installations: ReadonlySet<InstallationRecord>, configs: ReadonlyMap<InstallationRecord, unknown>, contracts: ContractRegistryDraft): Promise<void>;
+    activate(plan: InstallationGraph, installations: ReadonlySet<InstallationRecord>, configs: ReadonlyMap<InstallationRecord, unknown>, contracts: ContractRegistryWriter): Promise<void>;
+    /**
+     * Stops in reverse activation order, sequentially, and collects every failure
+     * instead of stopping at the first. A dependent must be gone before the
+     * Service it consumed, and one Instance that refuses to shut down cleanly must
+     * not leave the rest running — its error is returned, not thrown.
+     */
     deactivate(installations: ReadonlySet<InstallationRecord>): Promise<unknown[]>;
+    /**
+     * Runs one operation with contribution publication deferred to its end, so a
+     * change that withdraws and adds contributions is observed once rather than as
+     * an intermediate state.
+     *
+     * Publication happens even when the operation failed, because contributions
+     * withdrawn by Instances that did stop must not stay visible. If both the
+     * operation and the publication fail, both errors are reported — the
+     * publication failure must not hide the reason the change failed, and the
+     * operation failure must not hide a store left inconsistent.
+     */
     withContributionBatch<T>(operation: () => Promise<T>): Promise<T>;
 }
 //# sourceMappingURL=instance-coordinator.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"instance-coordinator.d.ts","sourceRoot":"","sources":["../src/instance-coordinator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAA8B,KAAK,cAAc,EAAoB,MAAM,aAAa,CAAC;AAChG,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAY,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAkD,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAazF,MAAM,WAAW,uBAAuB;IACtC,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,qBAAa,gCAAiC,SAAQ,cAAc;CAAG;AAEvE,+EAA+E;AAC/E,qBAAa,mBAAmB;;gBAUlB,IAAI,EAAE,uBAAuB;IAQzC,WAAW,CAAC,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM;;;;;;;IAO3D,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;IAIzC,cAAc,CAAC,aAAa,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAS1D,oBAAoB;IAKpB,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC;IAI9D,aAAa;IAIP,QAAQ,CACZ,IAAI,EAAE,iBAAiB,EACvB,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAC9C,OAAO,EAAE,WAAW,CAAC,kBAAkB,EAAE,OAAO,CAAC,EACjD,SAAS,EAAE,qBAAqB;IA6D5B,UAAU,CAAC,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC;IAwBzD,qBAAqB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;CAsO3D"}
+{"version":3,"file":"instance-coordinator.d.ts","sourceRoot":"","sources":["../src/instance-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAA8B,KAAK,cAAc,EAAoB,MAAM,aAAa,CAAC;AAChG,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAY,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAkD,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAazF,MAAM,WAAW,uBAAuB;IACtC,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,qBAAa,gCAAiC,SAAQ,cAAc;CAAG;AAEvE;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;;gBAUlB,IAAI,EAAE,uBAAuB;IAQzC,WAAW,CAAC,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM;;;;;;;IAO3D,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;IAIzC,cAAc,CAAC,aAAa,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAS1D,oBAAoB;IAKpB,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC;IAI9D,aAAa;IAIP,QAAQ,CACZ,IAAI,EAAE,iBAAiB,EACvB,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAC9C,OAAO,EAAE,WAAW,CAAC,kBAAkB,EAAE,OAAO,CAAC,EACjD,SAAS,EAAE,sBAAsB;IAgEnC;;;;;OAKG;IACG,UAAU,CAAC,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC;IAwB/D;;;;;;;;;;OAUG;IACG,qBAAqB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;CAoP3D"}

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

@@ -1 +1 @@
-{"version":3,"file":"lifecycle-status.d.ts","sourceRoot":"","sources":["../src/lifecycle-status.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC"}
+{"version":3,"file":"lifecycle-status.d.ts","sourceRoot":"","sources":["../src/lifecycle-status.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC"}

package/dist/lifetime-diagnostics.d.ts

@@ -13,7 +13,13 @@ export interface LifetimeSnapshot {
     readonly children: ReadonlyArray<LifetimeSnapshot>;
 }
 export type LifetimeResourceKind = "cleanups" | "tasks" | "listeners" | "contributions" | "contributionViews" | "subscriptions";
-/** Internal state that mirrors a Lifetime without retaining any owned resource. */
+/**
+ * Internal state that mirrors a Lifetime without retaining any owned resource.
+ *
+ * Counts, not references. A diagnostics tree that held the listeners and tasks
+ * it describes would keep them alive precisely because someone was watching, so
+ * a node knows how many of each kind exist and nothing about what they are.
+ */
 export interface LifetimeDiagnosticNode {
     readonly label: string;
     readonly counts: Record<LifetimeResourceKind, number>;

package/dist/lifetime-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifetime-diagnostics.d.ts","sourceRoot":"","sources":["../src/lifetime-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEvE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;AAEhE,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,oBAAoB,GAC9B,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,eAAe,GAAG,mBAAmB,GAAG,eAAe,CAAC;AAE/F,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC/C,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,+EAA+E;AAC/E,qBAAa,mBAAmB;;IAG9B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC;gBAElC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAM/D,UAAU,CAAC,KAAK,EAAE,MAAM;IAIxB,MAAM,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB;IAMpE,MAAM,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB;IAKpE,MAAM,CAAC,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAO9E,cAAc,CAAC,IAAI,EAAE,sBAAsB;IAM3C,UAAU;CAMX"}
+{"version":3,"file":"lifetime-diagnostics.d.ts","sourceRoot":"","sources":["../src/lifetime-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEvE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;AAEhE,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,oBAAoB,GAC9B,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,eAAe,GAAG,mBAAmB,GAAG,eAAe,CAAC;AAE/F;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC/C,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,+EAA+E;AAC/E,qBAAa,mBAAmB;;IAG9B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC;gBAElC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAM/D,UAAU,CAAC,KAAK,EAAE,MAAM;IAIxB,MAAM,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB;IAMpE,MAAM,CAAC,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB;IAKpE,MAAM,CAAC,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAU9E,cAAc,CAAC,IAAI,EAAE,sBAAsB;IAM3C,UAAU;CAMX"}

package/dist/lifetime.d.ts

@@ -10,6 +10,11 @@ export interface Logger {
     readonly warn: (message: unknown, ...details: unknown[]) => void;
     readonly error: (message: unknown, ...details: unknown[]) => void;
 }
+/**
+ * Structural, so `console` and any four-method object both qualify without
+ * importing a Dougong type. The try/catch is for hostile getters: a validator
+ * must not throw the very error it was asked to prevent.
+ */
 export declare function isLogger(value: unknown): value is Logger;
 export interface InstanceMeta {
     readonly hostName: string;
@@ -23,6 +28,12 @@ export interface Task<T = void> extends AsyncDisposable {
 export type Cleanup = () => unknown;
 export type BackgroundTask<T> = (signal: AbortSignal) => T | PromiseLike<T>;
 type EventArguments<T> = [T] extends [void] ? [payload?: T] : [payload: T];
+/**
+ * The complete set of things an Instance can do. Seven members, each returning
+ * something the Lifetime already owns — there is no `register()` that takes a
+ * resource from elsewhere, which is why ownership is structural rather than a
+ * convention Plugin authors have to follow.
+ */
 export interface LifetimeOperations {
     readonly signal: AbortSignal;
     readonly cleanup: (dispose: Cleanup) => AsyncDisposable;
@@ -65,6 +76,15 @@ export declare class Lifetime implements LifetimeContext {
     /** A facade whose only InstanceCoordinator edge disappears when this Lifetime terminates. */
     contextLogger(meta: InstanceMeta): Logger;
     cleanup(dispose: Cleanup): CleanupRecord;
+    /**
+     * A child scope. It inherits this Lifetime's signal, so cancellation flows
+     * down, and its declaration phase, so a child created during `setup()` also
+     * stages rather than publishing immediately.
+     *
+     * Disposing a child detaches it from both the resource set and the diagnostics
+     * tree. A Plugin can therefore use child lifetimes as a unit of work — one per
+     * open document, per connection — without the parent growing.
+     */
     lifetime(label: string): LifetimeContext;
     spawn<T>(task: BackgroundTask<T>): Task<T>;
     on<T>(token: Event<T>, listener: EventListener<T>): Disposable;
@@ -74,8 +94,24 @@ export declare class Lifetime implements LifetimeContext {
     ownLease(resource: Disposable, kind: ContributionLeaseKind): () => boolean;
     /** Releases a temporary startup cancellation edge after its layer commits. */
     detachStartupSignal(): void;
-    /** Atomically makes all declarations staged during setup visible. */
+    /**
+     * Atomically makes all declarations staged during setup visible.
+     *
+     * Children publish too, recursively, so a Lifetime created inside `setup()`
+     * becomes visible with its parent rather than being stranded staged. Called by
+     * the InstanceCoordinator once the whole activation layer has succeeded —
+     * which is what makes "no half-built Instance is observable" true.
+     */
     publish(): void;
+    /**
+     * Disposal is idempotent and joinable: concurrent callers share one completion
+     * promise, so a Lifetime disposed by both its owner and a `using` block runs
+     * its teardown once.
+     *
+     * The three-stage order is the module header's; see it for why. Errors from
+     * every stage accumulate and are aggregated at the end, so one failing cleanup
+     * neither hides the others nor prevents them from running.
+     */
     dispose(): Promise<void>;
     [asyncDisposeSymbol](): Promise<void>;
 }

package/dist/lifetime.d.ts.map

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

package/dist/plugin.d.ts

@@ -5,6 +5,11 @@ import { InstanceMeta, LifetimeOperations, Logger } from './lifetime';
 import { Awaitable } from './resource';
 export type { Awaitable } from './resource';
 export type Requirements = Readonly<Record<string, Requirement>>;
+/**
+ * Only Services can be provided. An ExtensionPoint is an open set that many
+ * Installations contribute to, and an Event has no owner at all, so neither is
+ * something one Plugin can claim to supply.
+ */
 export type Provisions = Readonly<Record<string, Extract<Requirement, {
     readonly kind: "service";
 }>>>;
@@ -16,7 +21,21 @@ export type ResolvedRequirements<T extends Requirements> = {
 export type ProvidedServices<T extends Provisions> = {
     readonly [Key in keyof T]: ServiceValue<T[Key]>;
 };
+/**
+ * A Plugin that provides nothing returns `void`; one that provides Services must
+ * return exactly them. Forgetting a provided Service is therefore a compile
+ * error, not a `SERVICE_NOT_RETURNED` at activation time.
+ */
 type SetupOutput<T extends Provisions> = keyof T extends never ? void : ProvidedServices<T>;
+/**
+ * Everything one Instance can reach, and nothing more. Resolved requirements
+ * arrive under the same aliases they were declared with, alongside the Lifetime
+ * operations that own whatever `setup()` creates.
+ *
+ * There is no Host, no registry and no parent here. A Plugin's dependencies are
+ * exactly what it declared — which is what makes a declaration readable in
+ * isolation.
+ */
 export type PluginContext<T extends Requirements = Requirements> = LifetimeOperations & ResolvedRequirements<T> & {
     readonly meta: InstanceMeta;
     readonly log: Logger;
@@ -49,10 +68,17 @@ export type InstanceContext = LifetimeOperations & Readonly<Record<string, unkno
 export interface NormalizedPlugin {
     readonly name: string;
     readonly config?: StandardSchemaV1<unknown, unknown>;
-    readonly requires?: Requirements;
-    readonly provides?: Provisions;
+    readonly requires: Requirements;
+    readonly provides: Provisions;
     readonly setup: (context: InstanceContext, config: unknown) => Awaitable<void | Readonly<Record<string, unknown>>>;
 }
+/**
+ * Validates and freezes a Plugin declaration.
+ *
+ * The `NoInfer` wrappers on the return type stop a caller's annotation from
+ * widening the inferred generics back out, which would let `setup()` see a
+ * looser context than the declaration actually promises.
+ */
 export declare function definePlugin<Config = void, Requires extends Requirements = {}, Provides extends Provisions = {}, ConfigInput = Config>(plugin: Plugin<Config, Requires, Provides, ConfigInput>): Plugin<NoInfer<Config>, NoInfer<Requires>, NoInfer<Provides>, NoInfer<ConfigInput>>;
 /** The sole boundary that validates a public Plugin and erases authoring-only generics. */
 export declare function normalizePlugin(plugin: AnyPlugin): NormalizedPlugin;

package/dist/plugin.d.ts.map

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

package/dist/readonly-map.d.ts

@@ -1,4 +1,11 @@
-/** A structural snapshot that exposes no mutating Map methods. */
+/**
+ * A structural snapshot that exposes no mutating Map methods.
+ *
+ * `ReadonlyMap` is only a compile-time view — casting a live `Map` to it still
+ * hands out an object whose `set` and `delete` are one cast away. This copies on
+ * construction and freezes itself, so a published snapshot cannot be edited by
+ * whoever received it, and cannot change under a reader afterwards.
+ */
 export declare class ReadonlyMapSnapshot<Key, Value> implements ReadonlyMap<Key, Value> {
     #private;
     constructor(values?: ReadonlyMap<Key, Value> | Iterable<readonly [Key, Value]>);

package/dist/readonly-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"readonly-map.d.ts","sourceRoot":"","sources":["../src/readonly-map.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,qBAAa,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAE,YAAW,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC;;gBAGjE,MAAM,GAAE,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAM;IAYlF,IAAI,IAAI,WAEP;IAED,GAAG,CAAC,GAAG,EAAE,GAAG;IAIZ,GAAG,CAAC,GAAG,EAAE,GAAG;IAIZ,OAAO,CACL,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,IAAI,EACxE,OAAO,CAAC,EAAE,OAAO;IAKnB,OAAO;IAIP,IAAI;IAIJ,MAAM;IAIN,CAAC,MAAM,CAAC,QAAQ,CAAC;CAGlB"}
+{"version":3,"file":"readonly-map.d.ts","sourceRoot":"","sources":["../src/readonly-map.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAE,YAAW,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC;;gBAGjE,MAAM,GAAE,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAM;IAYlF,IAAI,IAAI,WAEP;IAED,GAAG,CAAC,GAAG,EAAE,GAAG;IAIZ,GAAG,CAAC,GAAG,EAAE,GAAG;IAIZ,OAAO,CACL,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,IAAI,EACxE,OAAO,CAAC,EAAE,OAAO;IAKnB,OAAO;IAIP,IAAI;IAIJ,MAAM;IAIN,CAAC,MAAM,CAAC,QAAQ,CAAC;CAGlB"}

package/dist/record.d.ts

@@ -1,8 +1,23 @@
 interface PlainRecordOptions {
+    /** When present, any key outside this set is rejected instead of ignored. */
     readonly fields?: ReadonlySet<string>;
+    /** Lets a caller raise its own coded error instead of a bare `TypeError`. */
     readonly createError?: (message: string) => Error;
 }
-/** Validates declaration bags without reading through their prototype chain. */
+/**
+ * Validates declaration bags without reading through their prototype chain.
+ *
+ * Every option object Core accepts passes through here. The checks look
+ * paranoid, and each one closes a way for a declaration to lie:
+ *
+ * - a non-`Object.prototype` prototype could answer for keys it does not own;
+ * - a non-enumerable or symbol key would escape the field allowlist;
+ * - a getter (`{ get name() {...} }`) would return a different value on the
+ *   second read, so validation would not describe what gets stored.
+ *
+ * Rejecting an unknown field rather than ignoring it turns a typo — `permissions`
+ * for `authorizer` — into an error at the call site instead of silence.
+ */
 export declare function assertPlainRecord(value: unknown, label: string, options?: PlainRecordOptions): asserts value is object;
 export {};
 //# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAAA,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;CACnD;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,KAAK,IAAI,MAAM,CAoBzB"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAAA,UAAU,kBAAkB;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;CACnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,KAAK,IAAI,MAAM,CAoBzB"}

package/dist/resource.d.ts

@@ -16,9 +16,15 @@ export interface AsyncDisposable {
     [Symbol.asyncDispose](): Promise<void>;
 }
 export type Resource = Disposable | AsyncDisposable;
+/**
+ * A resource created in one step and made visible in another. Declarations made
+ * during `setup()` stage first and publish only once their whole layer
+ * activates, so no half-built Instance is ever observable.
+ */
 export interface Publication extends Disposable {
     publish(): void;
 }
+/** A Publication paired with the public handle its owner hands to Plugin code. */
 export interface StagedResource<T extends Disposable> extends Publication {
     readonly handle: T;
 }

package/dist/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAE9C,mGAAmG;AACnG,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,OAAO,GACrB,OAAO,CAAC,aAAa,IAAI,OAAO,OAAO,CAAC,aAAa,CAIvD;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,gBAAgB,GAAG,qBAAqB,UAG/C;AAID,yEAAyE;AACzE,eAAO,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC,OAGhB,CAAC;AAC3B,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC,YAGhB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,eAAe,CAAC;AAEpD,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,WAAW;IACvE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAE9C,mGAAmG;AACnG,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,OAAO,GACrB,OAAO,CAAC,aAAa,IAAI,OAAO,OAAO,CAAC,aAAa,CAIvD;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,gBAAgB,GAAG,qBAAqB,UAG/C;AAID,yEAAyE;AACzE,eAAO,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC,OAGhB,CAAC;AAC3B,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC,YAGhB,CAAC;AAMhC,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,eAAe,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,WAAW;IACvE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB"}

package/dist/serial-queue.d.ts

@@ -1,4 +1,10 @@
-/** Serial execution where each caller keeps its own result and failures do not poison the tail. */
+/**
+ * Serial execution where each caller keeps its own result and failures do not
+ * poison the tail.
+ *
+ * This is the Host's command boundary: one queue is the reason two concurrent
+ * `install()` calls cannot interleave their transactions.
+ */
 export declare class SerialQueue {
     #private;
     get settled(): Promise<void>;

package/dist/serial-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serial-queue.d.ts","sourceRoot":"","sources":["../src/serial-queue.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,qBAAa,WAAW;;IAGtB,IAAI,OAAO,kBAEV;IAED,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWxD"}
+{"version":3,"file":"serial-queue.d.ts","sourceRoot":"","sources":["../src/serial-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,WAAW;;IAGtB,IAAI,OAAO,kBAEV;IAED,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAcxD"}

package/dist/snapshot-view.d.ts

@@ -3,6 +3,8 @@ export interface SnapshotView<T> {
     get(): T;
     subscribe(listener: () => void): Disposable;
 }
+/** Internal synchronous commit boundary for related snapshots. */
+export declare function batchSnapshotNotifications(operation: () => void): void;
 /** Synchronous writer for immutable operational snapshots. */
 export declare class SnapshotPublisher<T> implements Disposable {
     #private;

package/dist/snapshot-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot-view.d.ts","sourceRoot":"","sources":["../src/snapshot-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAG5D,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,IAAI,CAAC,CAAC;IACT,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;CAC7C;AAoBD,8DAA8D;AAC9D,qBAAa,iBAAiB,CAAC,CAAC,CAAE,YAAW,UAAU;;gBAMzC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAU3D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAG3B;IAEH,UAAU;IAuBV,OAAO;IAcP,CAAC,aAAa,CAAC;CAgChB"}
+{"version":3,"file":"snapshot-view.d.ts","sourceRoot":"","sources":["../src/snapshot-view.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAG5D,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,IAAI,CAAC,CAAC;IACT,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;CAC7C;AAwBD,kEAAkE;AAClE,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,IAAI,QAmB/D;AA6BD,8DAA8D;AAC9D,qBAAa,iBAAiB,CAAC,CAAC,CAAE,YAAW,UAAU;;gBAMzC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAU3D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAG3B;IAEH,UAAU;IAOV,OAAO;IAiBP,CAAC,aAAa,CAAC;CAgChB"}

package/dist/sync-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-result.d.ts","sourceRoot":"","sources":["../src/sync-result.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQvE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAGxE"}
+{"version":3,"file":"sync-result.d.ts","sourceRoot":"","sources":["../src/sync-result.ts"],"names":[],"mappings":"AAaA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQvE;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAGxE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougongjs/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "engines": {
     "node": ">=22"