@peerbit/program 6.0.34 → 6.0.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/program.ts CHANGED
@@ -17,6 +17,13 @@ import {
17
17
  Handler,
18
18
  type Manageable,
19
19
  type ProgramInitializationOptions,
20
+ TERMINAL_BASE_CHECKPOINT,
21
+ TERMINAL_BASE_COMMIT,
22
+ TERMINAL_BASE_RETRY,
23
+ TERMINAL_OUTER_CLEANUP_RELEASE,
24
+ TERMINAL_OUTER_CLEANUP_RETAIN,
25
+ type TerminalBaseCommit,
26
+ TerminalOperationNotStartedError,
20
27
  addParent,
21
28
  } from "./handler.js";
22
29
  import { getValuesWithType } from "./utils.js";
@@ -77,6 +84,7 @@ class ProgramHandler extends Handler<Program> {
77
84
  identity: properties.client.identity,
78
85
  client: properties.client,
79
86
  shouldMonitor: (p) => p instanceof Program,
87
+ getDependencies: (program) => program.allPrograms,
80
88
  load: Program.load,
81
89
  });
82
90
  }
@@ -87,6 +95,32 @@ type ExtractArgs<T> = T extends Program<infer Args> ? Args : never;
87
95
 
88
96
  const PROGRAM_INSTANCE_SYMBOL = Symbol.for("@peerbit/program/Program");
89
97
 
98
+ type TerminalOperation = "close" | "drop";
99
+ type TerminalCall = {
100
+ type: TerminalOperation;
101
+ from?: Program;
102
+ terminal: boolean;
103
+ promise: Promise<boolean>;
104
+ };
105
+ type FailedTerminalChild = {
106
+ program: Program;
107
+ operation: TerminalOperation;
108
+ commit?: TerminalBaseCommit;
109
+ cleanupLease?: object;
110
+ };
111
+ type TerminalRetryContext = {
112
+ commit: TerminalBaseCommit;
113
+ consumed: boolean;
114
+ promise: Promise<boolean>;
115
+ };
116
+ type PendingTerminalTail = {
117
+ type: TerminalOperation;
118
+ from?: Program;
119
+ hadParentReference: boolean;
120
+ eventEmitted: boolean;
121
+ callbackCompleted: boolean;
122
+ };
123
+
90
124
  @variant(0)
91
125
  export abstract class Program<
92
126
  Args = any,
@@ -132,9 +166,30 @@ export abstract class Program<
132
166
 
133
167
  private _node: ProgramClient;
134
168
  private _allPrograms: Program[] | undefined;
169
+ private _acceptsParentAttachments = true;
135
170
 
136
171
  private _events: TypedEventTarget<ProgramEvents>;
137
172
  private _closed: boolean;
173
+ private _terminalCalls: TerminalCall[] | undefined;
174
+ private _dropDeletePending: boolean | undefined;
175
+ private _failedTerminalChildren: FailedTerminalChild[] | undefined;
176
+ private _emittedTerminalEvents: Set<TerminalOperation> | undefined;
177
+ private _terminalBaseCommitVersion: number | undefined;
178
+ private _terminalBaseCommitEpoch: number | undefined;
179
+ private _terminalBaseCommitsByParent:
180
+ | WeakMap<
181
+ Manageable<any>,
182
+ Partial<Record<TerminalOperation, TerminalBaseCommit>>
183
+ >
184
+ | undefined;
185
+ private _rootTerminalBaseCommits:
186
+ | Partial<Record<TerminalOperation, TerminalBaseCommit>>
187
+ | undefined;
188
+ private _terminalRetryContexts: TerminalRetryContext[] | undefined;
189
+ private _pendingTerminalTail: PendingTerminalTail | undefined;
190
+ private _terminalLifecycleCallbackRunning = false;
191
+ private _terminalOuterCleanupLeases: Set<object> | undefined;
192
+ private _pendingInverseParentReleases: Map<Program, number> | undefined;
138
193
 
139
194
  parents: (Program<any> | undefined)[];
140
195
  children: Program<Args>[];
@@ -198,6 +253,34 @@ export abstract class Program<
198
253
  this._closed = closed;
199
254
  }
200
255
 
256
+ get acceptsParentAttachments(): boolean {
257
+ // Program clones are borsh-created without running class field initializers.
258
+ return (
259
+ this._acceptsParentAttachments !== false &&
260
+ (this._terminalOuterCleanupLeases?.size ?? 0) === 0
261
+ );
262
+ }
263
+
264
+ get pendingTerminalOperation(): TerminalOperation | undefined {
265
+ return (
266
+ this._pendingTerminalTail?.type ||
267
+ (this._dropDeletePending ? "drop" : undefined)
268
+ );
269
+ }
270
+
271
+ get terminalLifecycleCallbackRunning(): boolean {
272
+ return this._terminalLifecycleCallbackRunning;
273
+ }
274
+
275
+ /**
276
+ * Fence Handler reuse while a subclass performs irreversible terminal work
277
+ * before delegating to Program.end(). A subsequent successful reopen clears
278
+ * the fence in beforeOpen().
279
+ */
280
+ protected preventParentAttachments(): void {
281
+ this._acceptsParentAttachments = false;
282
+ }
283
+
201
284
  get node(): ProgramClient {
202
285
  return this._node;
203
286
  }
@@ -212,6 +295,25 @@ export abstract class Program<
212
295
  node: ProgramClient,
213
296
  options?: ProgramInitializationOptions<Args, this>,
214
297
  ) {
298
+ if ((this._terminalOuterCleanupLeases?.size ?? 0) > 0) {
299
+ throw new Error(
300
+ "Program terminal cleanup must finish before the program can reopen",
301
+ );
302
+ }
303
+ if (this.closed) {
304
+ if (this._pendingTerminalTail || this._dropDeletePending) {
305
+ throw new Error(
306
+ "Program terminal cleanup must finish before the program can reopen",
307
+ );
308
+ }
309
+ this._terminalBaseCommitEpoch = (this._terminalBaseCommitEpoch ?? 0) + 1;
310
+ this._acceptsParentAttachments = true;
311
+ this._failedTerminalChildren = undefined;
312
+ this._emittedTerminalEvents?.clear();
313
+ this._emittedTerminalEvents = undefined;
314
+ this._terminalBaseCommitsByParent = undefined;
315
+ this._rootTerminalBaseCommits = undefined;
316
+ }
215
317
  // check that a discriminator exist
216
318
  const schema = getSchema(this.constructor);
217
319
  if (!schema || typeof schema.variant !== "string") {
@@ -413,43 +515,448 @@ export abstract class Program<
413
515
  e: CustomEvent<UnsubcriptionEvent>,
414
516
  ) => void;
415
517
 
416
- private async processEnd(type: "drop" | "close") {
417
- if (!this.closed) {
418
- this.emitEvent(new CustomEvent(type, { detail: this }), true);
419
- if (type === "close") {
420
- this._eventOptions?.onClose?.(this);
421
- } else if (type === "drop") {
422
- this._eventOptions?.onDrop?.(this);
423
- } else {
424
- throw new Error("Unsupported event type: " + type);
425
- }
518
+ [TERMINAL_BASE_CHECKPOINT](): number {
519
+ return this._terminalBaseCommitVersion ?? 0;
520
+ }
426
521
 
427
- const promises: Promise<void | boolean>[] = [];
522
+ [TERMINAL_OUTER_CLEANUP_RETAIN](): object {
523
+ const lease = {};
524
+ const leases =
525
+ this._terminalOuterCleanupLeases ||
526
+ (this._terminalOuterCleanupLeases = new Set());
527
+ leases.add(lease);
528
+ return lease;
529
+ }
428
530
 
429
- if (this.children) {
430
- for (const program of this.children) {
431
- if (program.closed) {
432
- if (type === "close") {
433
- continue;
434
- }
435
- }
436
- promises.push(program[type](this as Program)); // TODO types
531
+ [TERMINAL_OUTER_CLEANUP_RELEASE](lease: object): void {
532
+ this._terminalOuterCleanupLeases?.delete(lease);
533
+ if (this._terminalOuterCleanupLeases?.size === 0) {
534
+ this._terminalOuterCleanupLeases = undefined;
535
+ this.reconcilePendingInverseParentReleases();
536
+ }
537
+ }
538
+
539
+ [TERMINAL_BASE_COMMIT](
540
+ afterVersion: number,
541
+ type: TerminalOperation,
542
+ from?: Manageable<any>,
543
+ ): TerminalBaseCommit | undefined {
544
+ const commit = from
545
+ ? this._terminalBaseCommitsByParent?.get(from)?.[type]
546
+ : this._rootTerminalBaseCommits?.[type];
547
+ return commit && commit.version > afterVersion ? commit : undefined;
548
+ }
549
+
550
+ async [TERMINAL_BASE_RETRY](
551
+ commit: TerminalBaseCommit,
552
+ operation: () => Promise<boolean>,
553
+ ): Promise<boolean> {
554
+ if (commit.epoch !== (this._terminalBaseCommitEpoch ?? 0)) {
555
+ throw new Error(
556
+ "Program terminal cleanup belongs to a stale open lifecycle",
557
+ );
558
+ }
559
+ const context: TerminalRetryContext = {
560
+ commit,
561
+ consumed: false,
562
+ promise: Promise.resolve(commit.result),
563
+ };
564
+ const contexts =
565
+ this._terminalRetryContexts || (this._terminalRetryContexts = []);
566
+ contexts.push(context);
567
+ try {
568
+ return await operation();
569
+ } finally {
570
+ const index = contexts.indexOf(context);
571
+ if (index !== -1) contexts.splice(index, 1);
572
+ if (contexts.length === 0) this._terminalRetryContexts = undefined;
573
+ }
574
+ }
575
+
576
+ private consumeTerminalRetry(
577
+ type: TerminalOperation,
578
+ from?: Program,
579
+ ): Promise<boolean> | undefined {
580
+ const context = this._terminalRetryContexts?.find(
581
+ (candidate) =>
582
+ !candidate.consumed &&
583
+ candidate.commit.type === type &&
584
+ candidate.commit.from === from,
585
+ );
586
+ if (!context) return undefined;
587
+ context.consumed = true;
588
+ return context.promise;
589
+ }
590
+
591
+ private recordTerminalBaseCommit(
592
+ type: TerminalOperation,
593
+ from: Program | undefined,
594
+ result: boolean,
595
+ releasedParentReferences: number,
596
+ ): void {
597
+ const version = (this._terminalBaseCommitVersion ?? 0) + 1;
598
+ this._terminalBaseCommitVersion = version;
599
+ const commit = {
600
+ epoch: this._terminalBaseCommitEpoch ?? 0,
601
+ version,
602
+ type,
603
+ from,
604
+ result,
605
+ releasedParentReferences,
606
+ };
607
+ if (from) {
608
+ const commits =
609
+ this._terminalBaseCommitsByParent?.get(from) ??
610
+ ({} as Partial<Record<TerminalOperation, TerminalBaseCommit>>);
611
+ commits[type] = commit;
612
+ const commitsByParent =
613
+ this._terminalBaseCommitsByParent ||
614
+ (this._terminalBaseCommitsByParent = new WeakMap());
615
+ commitsByParent.set(from, commits);
616
+ } else {
617
+ const commits =
618
+ this._rootTerminalBaseCommits || (this._rootTerminalBaseCommits = {});
619
+ commits[type] = commit;
620
+ }
621
+ }
622
+
623
+ private retainInverseParentRelease(from: Program | undefined): void {
624
+ if (!from) return;
625
+ const pending =
626
+ this._pendingInverseParentReleases ||
627
+ (this._pendingInverseParentReleases = new Map());
628
+ pending.set(from, (pending.get(from) ?? 0) + 1);
629
+ }
630
+
631
+ private reconcilePendingInverseParentReleases(from?: Program): void {
632
+ const pending = this._pendingInverseParentReleases;
633
+ if (!pending) return;
634
+ const parents = from ? [from] : [...pending.keys()];
635
+ for (const parent of parents) {
636
+ let releasedReferences = pending.get(parent) ?? 0;
637
+ const retainedReferences =
638
+ this.parents?.filter((candidate) => candidate === parent).length ?? 0;
639
+ while (releasedReferences > 0) {
640
+ const inverseReferences =
641
+ parent.children?.filter((candidate) => candidate === this).length ??
642
+ 0;
643
+ if (inverseReferences > retainedReferences) {
644
+ const childIndex = parent.children.indexOf(this);
645
+ if (childIndex !== -1) parent.children.splice(childIndex, 1);
437
646
  }
438
- this.children = [];
647
+ releasedReferences -= 1;
439
648
  }
440
- await Promise.all(promises);
649
+ pending.delete(parent);
650
+ }
651
+ if (pending.size === 0) this._pendingInverseParentReleases = undefined;
652
+ }
441
653
 
442
- this._clear();
443
- this.closed = true;
444
- return true;
445
- } else {
654
+ private isOutermostBaseTerminalOperation(type: TerminalOperation): boolean {
655
+ const current = type === "close" ? this.close : this.drop;
656
+ const base =
657
+ type === "close" ? Program.prototype.close : Program.prototype.drop;
658
+ return current === base;
659
+ }
660
+
661
+ private async processEnd(
662
+ type: TerminalOperation,
663
+ from: Program | undefined,
664
+ hadParentReference: boolean,
665
+ ) {
666
+ if (this.closed) {
446
667
  this._clear();
447
668
  return true;
448
669
  }
670
+ // Lifecycle events retain their historical attempt semantics and parent-first
671
+ // ordering. A failed attempt emits once; retries in the same open epoch do not
672
+ // emit a duplicate event. The awaited onClose/onDrop callback below remains a
673
+ // committed-tail callback and only runs after children have drained.
674
+ const emittedTerminalEvents =
675
+ this._emittedTerminalEvents ||
676
+ (this._emittedTerminalEvents = new Set<TerminalOperation>());
677
+ const retryingTerminalAttempt = emittedTerminalEvents.has(type);
678
+ if (!emittedTerminalEvents.has(type)) {
679
+ emittedTerminalEvents.add(type);
680
+ this.emitEvent(new CustomEvent(type, { detail: this }), true);
681
+ }
682
+
683
+ const children = [...(this.children ?? [])];
684
+ const previousFailures = [...(this._failedTerminalChildren ?? [])];
685
+ const claimedFailures = new Set<FailedTerminalChild>();
686
+ const attempts: {
687
+ child: Program;
688
+ operation: TerminalOperation;
689
+ previous?: FailedTerminalChild;
690
+ checkpoint: number;
691
+ startedClosed: boolean;
692
+ ownerReferencesBefore: number;
693
+ inverseOwnerReferencesBefore: number;
694
+ skipped: boolean;
695
+ cleanupLease?: object;
696
+ }[] = [];
697
+ const tailsByChild = new Map<Program, Promise<boolean>>();
698
+ const childPromises = children.map((child) => {
699
+ const previous = previousFailures.find(
700
+ (failure) => failure.program === child && !claimedFailures.has(failure),
701
+ );
702
+ if (previous) claimedFailures.add(previous);
703
+ const attempt = {
704
+ child,
705
+ operation:
706
+ previous?.operation ?? child.pendingTerminalOperation ?? type,
707
+ previous,
708
+ checkpoint: 0,
709
+ startedClosed: false,
710
+ ownerReferencesBefore: 0,
711
+ inverseOwnerReferencesBefore: 0,
712
+ skipped: false,
713
+ cleanupLease: previous?.cleanupLease,
714
+ };
715
+ attempts.push(attempt);
716
+ const run = async () => {
717
+ attempt.startedClosed = child.closed;
718
+ attempt.ownerReferencesBefore =
719
+ child.parents?.filter((parent) => parent === this).length ?? 0;
720
+ attempt.inverseOwnerReferencesBefore =
721
+ this.children?.filter((candidate) => candidate === child).length ?? 0;
722
+ if (
723
+ child.closed &&
724
+ (attempt.operation === "close" || retryingTerminalAttempt) &&
725
+ !previous &&
726
+ !child.pendingTerminalOperation
727
+ ) {
728
+ return true;
729
+ }
730
+ attempt.cleanupLease ??= child[TERMINAL_OUTER_CLEANUP_RETAIN]();
731
+ attempt.checkpoint = child[TERMINAL_BASE_CHECKPOINT]();
732
+ const invoke = () => child[attempt.operation](this as Program);
733
+ const result = await (previous?.commit
734
+ ? child[TERMINAL_BASE_RETRY](previous.commit, invoke)
735
+ : invoke());
736
+ const ownerReferencesAfter =
737
+ child.parents?.filter((parent) => parent === this).length ?? 0;
738
+ let inverseOwnerReferencesAfter =
739
+ this.children?.filter((candidate) => candidate === child).length ?? 0;
740
+ // A child override must not be able to hide a retained owner by deleting
741
+ // only the parent's inverse edge. Restore the minimum graph reachability
742
+ // required by the child's live owner references before validating progress.
743
+ while (inverseOwnerReferencesAfter < ownerReferencesAfter) {
744
+ this.children.push(child);
745
+ inverseOwnerReferencesAfter += 1;
746
+ }
747
+ // A successful retry may consume a previously committed parent release
748
+ // without changing the child's owner list again. Reconcile at most the one
749
+ // stale inverse edge represented by this occurrence before deciding whether
750
+ // the call made progress.
751
+ if (inverseOwnerReferencesAfter > ownerReferencesAfter) {
752
+ const childIndex = this.children.indexOf(child);
753
+ if (childIndex !== -1) {
754
+ this.children.splice(childIndex, 1);
755
+ inverseOwnerReferencesAfter -= 1;
756
+ }
757
+ }
758
+ const committedRelease =
759
+ (previous?.commit?.releasedParentReferences ?? 0) > 0;
760
+ const releasedOwnerReference =
761
+ ownerReferencesAfter < attempt.ownerReferencesBefore;
762
+ const repairedStaleInverseReference =
763
+ attempt.inverseOwnerReferencesBefore >
764
+ attempt.ownerReferencesBefore &&
765
+ ownerReferencesAfter === attempt.ownerReferencesBefore &&
766
+ inverseOwnerReferencesAfter < attempt.inverseOwnerReferencesBefore;
767
+ if (
768
+ !attempt.startedClosed &&
769
+ !child.closed &&
770
+ !committedRelease &&
771
+ !releasedOwnerReference &&
772
+ !repairedStaleInverseReference
773
+ ) {
774
+ throw new Error(
775
+ `Child program at ${child.address} did not release parent ownership during ${attempt.operation}`,
776
+ );
777
+ }
778
+ return result;
779
+ };
780
+ const predecessor = tailsByChild.get(child);
781
+ const promise = predecessor
782
+ ? predecessor.then(run, (error) => {
783
+ // Duplicate appearances represent distinct ownership references.
784
+ // Do not spend the next reference while cleanup for the preceding
785
+ // release is unresolved; retain it for the recovery attempt.
786
+ attempt.skipped = true;
787
+ throw error;
788
+ })
789
+ : run();
790
+ tailsByChild.set(child, promise);
791
+ return promise;
792
+ });
793
+ const results = await Promise.allSettled(childPromises);
794
+ const failedChildren: FailedTerminalChild[] = [];
795
+ let firstChildError: unknown;
796
+ for (let index = 0; index < results.length; index++) {
797
+ const result = results[index]!;
798
+ const attempt = attempts[index]!;
799
+ const child = attempt.child;
800
+ if (result.status === "rejected") {
801
+ if (attempt.skipped) {
802
+ if (attempt.previous) failedChildren.push(attempt.previous);
803
+ firstChildError ??= result.reason;
804
+ continue;
805
+ }
806
+ if (!attempt.startedClosed || attempt.previous) {
807
+ const ownerReferencesAfter =
808
+ child.parents?.filter((parent) => parent === this).length ?? 0;
809
+ const commit =
810
+ attempt.previous?.commit ||
811
+ child[TERMINAL_BASE_COMMIT](
812
+ attempt.checkpoint,
813
+ attempt.operation,
814
+ this,
815
+ );
816
+ const baseProgressed =
817
+ commit != null ||
818
+ child.closed !== attempt.startedClosed ||
819
+ ownerReferencesAfter !== attempt.ownerReferencesBefore;
820
+ const retainCleanupLease =
821
+ baseProgressed ||
822
+ attempt.previous != null ||
823
+ !(result.reason instanceof TerminalOperationNotStartedError);
824
+ const cleanupLease = retainCleanupLease
825
+ ? attempt.cleanupLease
826
+ : undefined;
827
+ if (!retainCleanupLease && attempt.cleanupLease) {
828
+ child[TERMINAL_OUTER_CLEANUP_RELEASE](attempt.cleanupLease);
829
+ attempt.cleanupLease = undefined;
830
+ }
831
+ failedChildren.push({
832
+ program: child,
833
+ operation:
834
+ attempt.operation === "drop" && !baseProgressed
835
+ ? "drop"
836
+ : commit || child.closed
837
+ ? attempt.operation
838
+ : "close",
839
+ commit,
840
+ cleanupLease,
841
+ });
842
+ } else if (attempt.cleanupLease) {
843
+ child[TERMINAL_OUTER_CLEANUP_RELEASE](attempt.cleanupLease);
844
+ attempt.cleanupLease = undefined;
845
+ }
846
+ firstChildError ??= result.reason;
847
+ continue;
848
+ }
849
+ if (attempt.cleanupLease) {
850
+ child[TERMINAL_OUTER_CLEANUP_RELEASE](attempt.cleanupLease);
851
+ attempt.cleanupLease = undefined;
852
+ }
853
+ // A managed child's Handler may already have reconciled the inverse edge
854
+ // from its committed base release. Nested unmanaged children rely on this
855
+ // parent instead. Remove at most the one excess edge represented by this
856
+ // successful occurrence so both paths remain count-correct.
857
+ const childReferences =
858
+ child.parents?.filter((parent) => parent === this).length ?? 0;
859
+ const childEdges =
860
+ this.children?.filter((candidate) => candidate === child).length ?? 0;
861
+ if (childEdges > childReferences) {
862
+ const childIndex = this.children.indexOf(child);
863
+ if (childIndex !== -1) this.children.splice(childIndex, 1);
864
+ }
865
+ }
866
+ for (const previous of previousFailures) {
867
+ if (!claimedFailures.has(previous) && previous.cleanupLease) {
868
+ previous.program[TERMINAL_OUTER_CLEANUP_RELEASE](previous.cleanupLease);
869
+ previous.cleanupLease = undefined;
870
+ }
871
+ }
872
+ this._failedTerminalChildren =
873
+ failedChildren.length > 0 ? failedChildren : undefined;
874
+ if (firstChildError !== undefined) throw firstChildError;
875
+
876
+ this._clear();
877
+ this.closed = true;
878
+ this._pendingTerminalTail = {
879
+ type,
880
+ from,
881
+ hadParentReference,
882
+ eventEmitted: true,
883
+ callbackCompleted: false,
884
+ };
885
+ await this.finishTerminalTail();
886
+ return true;
887
+ }
888
+
889
+ private async finishTerminalTail(): Promise<void> {
890
+ const tail = this._pendingTerminalTail;
891
+ if (!tail) return;
892
+ if (!tail.eventEmitted) {
893
+ tail.eventEmitted = true;
894
+ const emittedTerminalEvents =
895
+ this._emittedTerminalEvents ||
896
+ (this._emittedTerminalEvents = new Set<TerminalOperation>());
897
+ if (!emittedTerminalEvents.has(tail.type)) {
898
+ emittedTerminalEvents.add(tail.type);
899
+ this.emitEvent(new CustomEvent(tail.type, { detail: this }), true);
900
+ }
901
+ }
902
+ if (!tail.callbackCompleted) {
903
+ const callback =
904
+ tail.type === "close"
905
+ ? this._eventOptions?.onClose
906
+ : this._eventOptions?.onDrop;
907
+ this._terminalLifecycleCallbackRunning = true;
908
+ try {
909
+ await callback?.(this);
910
+ } finally {
911
+ this._terminalLifecycleCallbackRunning = false;
912
+ }
913
+ tail.callbackCompleted = true;
914
+ }
915
+
916
+ this.node?.services.pubsub.removeEventListener(
917
+ "subscribe",
918
+ this._subscriptionEventListener,
919
+ );
920
+ this.node?.services.pubsub.removeEventListener(
921
+ "unsubscribe",
922
+ this._unsubscriptionEventListener,
923
+ );
924
+ this._emittedEventsFor?.clear();
925
+ this._emittedEventsFor = undefined;
926
+ this._peerTopicsByHash?.clear();
927
+ this._peerTopicsByHash = undefined;
928
+ this._seedPeerTopicsFromSubscribers = undefined;
929
+ this._eventOptions = undefined;
930
+ if (tail.hadParentReference) {
931
+ const parentIndex =
932
+ this.parents?.findIndex((parent) => parent === tail.from) ?? -1;
933
+ if (parentIndex !== -1) {
934
+ this.parents.splice(parentIndex, 1);
935
+ this.retainInverseParentRelease(tail.from);
936
+ }
937
+ }
938
+ this._pendingTerminalTail = undefined;
449
939
  }
450
940
 
451
- private async end(type: "drop" | "close", from?: Program): Promise<boolean> {
941
+ private async end(type: TerminalOperation, from?: Program): Promise<boolean> {
452
942
  if (this.closed) {
943
+ if (
944
+ this._pendingTerminalTail &&
945
+ this._pendingTerminalTail.type !== type
946
+ ) {
947
+ throw new Error(
948
+ `Program has pending ${this._pendingTerminalTail.type} cleanup; retry it before ${type}`,
949
+ );
950
+ }
951
+ if (this._pendingTerminalTail) {
952
+ await this.finishTerminalTail();
953
+ return true;
954
+ }
955
+ if (this._dropDeletePending && type === "close") {
956
+ throw new Error(
957
+ "Program has pending drop deletion; retry drop before close",
958
+ );
959
+ }
453
960
  if (type === "drop") {
454
961
  throw new ClosedError("Program is closed, can not drop");
455
962
  }
@@ -465,50 +972,168 @@ export abstract class Program<
465
972
  close = true;
466
973
  } else {
467
974
  this.parents.splice(parentIdx, 1);
975
+ this.retainInverseParentRelease(from);
468
976
  close = false;
469
977
  }
470
978
  } else if (from) {
471
- throw new Error("Could not find from in parents");
979
+ throw new TerminalOperationNotStartedError(
980
+ "Could not find from in parents",
981
+ );
472
982
  }
473
983
  }
474
984
 
475
- const end = close && (await this.processEnd(type));
476
- if (end) {
477
- this.node?.services.pubsub.removeEventListener(
478
- "subscribe",
479
- this._subscriptionEventListener,
480
- );
481
- this.node?.services.pubsub.removeEventListener(
482
- "unsubscribe",
483
- this._unsubscriptionEventListener,
484
- );
485
- this._emittedEventsFor?.clear();
486
- this._emittedEventsFor = undefined;
487
- this._peerTopicsByHash?.clear();
488
- this._peerTopicsByHash = undefined;
489
- this._seedPeerTopicsFromSubscribers = undefined;
490
-
491
- this._eventOptions = undefined;
492
-
493
- if (parentIdx !== -1) {
494
- this.parents.splice(parentIdx, 1); // We splice this here because this._end depends on this parent to exist
495
- }
985
+ if (close) {
986
+ // Establish the reuse fence synchronously once this call owns terminal
987
+ // shutdown. Non-terminal parent releases remain attachable.
988
+ this.preventParentAttachments();
496
989
  }
497
- return end;
990
+ return close && (await this.processEnd(type, from, parentIdx !== -1));
498
991
  }
499
- async close(from?: Program): Promise<boolean> {
500
- this._emittedEventsFor = undefined;
501
- return this.end("close", from);
992
+ private performTerminalOperation(
993
+ type: TerminalOperation,
994
+ from?: Program,
995
+ ): Promise<boolean> {
996
+ if (type === "close") {
997
+ this._emittedEventsFor = undefined;
998
+ return this.end("close", from);
999
+ }
1000
+ return this.performDrop(from);
502
1001
  }
503
1002
 
504
- async drop(from?: Program): Promise<boolean> {
1003
+ private async performDrop(from?: Program): Promise<boolean> {
1004
+ if (this.closed && this._dropDeletePending) {
1005
+ await this.delete();
1006
+ this._dropDeletePending = false;
1007
+ return true;
1008
+ }
1009
+
505
1010
  const dropped = await this.end("drop", from);
506
1011
  if (dropped) {
1012
+ // Remember the committed terminal transition before deletion. If rm()
1013
+ // fails, a later drop retry must resume here instead of rejecting merely
1014
+ // because Program.end() already made `closed` observable.
1015
+ this._dropDeletePending = true;
507
1016
  await this.delete();
1017
+ this._dropDeletePending = false;
508
1018
  }
509
1019
  return dropped;
510
1020
  }
511
1021
 
1022
+ private terminalOperation(
1023
+ type: TerminalOperation,
1024
+ from?: Program,
1025
+ ): Promise<boolean> {
1026
+ if (this._terminalLifecycleCallbackRunning) {
1027
+ return Promise.reject(
1028
+ new TerminalOperationNotStartedError(
1029
+ "Program lifecycle callbacks cannot wait for their own terminal operation",
1030
+ ),
1031
+ );
1032
+ }
1033
+ const retry = this.consumeTerminalRetry(type, from);
1034
+ if (retry) return retry;
1035
+ const calls = this._terminalCalls || (this._terminalCalls = []);
1036
+ const matching = calls.find(
1037
+ (call) => call.type === type && call.from === from && call.terminal,
1038
+ );
1039
+ if (matching) {
1040
+ return matching.promise;
1041
+ }
1042
+
1043
+ if (type === "close") {
1044
+ // Drop is the stronger terminal operation. A close admitted for the same
1045
+ // owner while drop is pending observes that exact operation and promise.
1046
+ const dropping = calls.find(
1047
+ (call) => call.type === "drop" && call.from === from && call.terminal,
1048
+ );
1049
+ if (dropping) {
1050
+ return dropping.promise;
1051
+ }
1052
+ }
1053
+
1054
+ const predecessor = calls.at(-1);
1055
+ let resolve!: (value: boolean) => void;
1056
+ let reject!: (reason?: unknown) => void;
1057
+ const promise = new Promise<boolean>((promiseResolve, promiseReject) => {
1058
+ resolve = promiseResolve;
1059
+ reject = promiseReject;
1060
+ });
1061
+ const parentIndex =
1062
+ this.parents?.findIndex((parent) => parent === from) ?? -1;
1063
+ const terminal =
1064
+ this.closed || parentIndex === -1 || (this.parents?.length ?? 0) === 1;
1065
+ const call: TerminalCall = { type, from, terminal, promise };
1066
+ calls.push(call);
1067
+
1068
+ const execute = () => {
1069
+ let operation: Promise<boolean>;
1070
+ const ownerReferencesBefore =
1071
+ this.parents?.filter((parent) => parent === from).length ?? 0;
1072
+ try {
1073
+ operation = this.performTerminalOperation(type, from);
1074
+ } catch (error) {
1075
+ reject(error);
1076
+ return;
1077
+ }
1078
+ void operation.then((result) => {
1079
+ const ownerReferencesAfter =
1080
+ this.parents?.filter((parent) => parent === from).length ?? 0;
1081
+ this.recordTerminalBaseCommit(
1082
+ type,
1083
+ from,
1084
+ result,
1085
+ Math.max(0, ownerReferencesBefore - ownerReferencesAfter),
1086
+ );
1087
+ // Program only owns the base promise. A subclass may still be doing
1088
+ // post-super terminal cleanup, so managed/embedded calls defer inverse-
1089
+ // edge removal to the caller's outer cleanup lease. A non-terminal owner
1090
+ // release leaves the child live and can reconcile immediately; an
1091
+ // inherited base method is itself the full public operation.
1092
+ if (
1093
+ (this._terminalOuterCleanupLeases?.size ?? 0) === 0 &&
1094
+ (!result || this.isOutermostBaseTerminalOperation(type))
1095
+ ) {
1096
+ this.reconcilePendingInverseParentReleases(result ? undefined : from);
1097
+ }
1098
+ resolve(result);
1099
+ }, reject);
1100
+ };
1101
+ if (predecessor) {
1102
+ // Different owners and close-vs-drop calls are serialized. In particular,
1103
+ // a drop admitted after close does not pretend destructive cleanup happened:
1104
+ // it runs after close and receives ClosedError from the now-closed program.
1105
+ void predecessor.promise.then(execute, execute);
1106
+ } else {
1107
+ execute();
1108
+ }
1109
+
1110
+ void promise.then(
1111
+ () => this.finishTerminalCall(call),
1112
+ () => this.finishTerminalCall(call),
1113
+ );
1114
+ return promise;
1115
+ }
1116
+
1117
+ private finishTerminalCall(call: TerminalCall): void {
1118
+ const calls = this._terminalCalls;
1119
+ const index = calls?.indexOf(call) ?? -1;
1120
+ if (index !== -1) {
1121
+ calls!.splice(index, 1);
1122
+ }
1123
+ if (calls?.length === 0) {
1124
+ this._terminalCalls = undefined;
1125
+ }
1126
+ }
1127
+
1128
+ close(from?: Program): Promise<boolean> {
1129
+ this._emittedEventsFor = undefined;
1130
+ return this.terminalOperation("close", from);
1131
+ }
1132
+
1133
+ drop(from?: Program): Promise<boolean> {
1134
+ return this.terminalOperation("drop", from);
1135
+ }
1136
+
512
1137
  emitEvent(event: CustomEvent, parents = false) {
513
1138
  this.events.dispatchEvent(event);
514
1139
  if (parents) {
@@ -545,7 +1170,9 @@ export abstract class Program<
545
1170
  throw new Error("Program has no topics, cannot get ready");
546
1171
  }
547
1172
  const pubsub = this.node.services.pubsub;
548
- const collectProvidedPublicKeys = (refs: PeerRefs): Map<string, PublicSignKey> => {
1173
+ const collectProvidedPublicKeys = (
1174
+ refs: PeerRefs,
1175
+ ): Map<string, PublicSignKey> => {
549
1176
  const providedPublicKeysByHash = new Map<string, PublicSignKey>();
550
1177
  const rememberPublicKey = (ref: unknown) => {
551
1178
  if (ref instanceof PublicSignKey) {
@@ -563,7 +1190,9 @@ export abstract class Program<
563
1190
  }
564
1191
  return providedPublicKeysByHash;
565
1192
  }
566
- if (typeof (refs as Iterable<unknown>)?.[Symbol.iterator] === "function") {
1193
+ if (
1194
+ typeof (refs as Iterable<unknown>)?.[Symbol.iterator] === "function"
1195
+ ) {
567
1196
  for (const ref of refs as Iterable<unknown>) {
568
1197
  rememberPublicKey(ref);
569
1198
  }
@@ -816,10 +1445,18 @@ export abstract class Program<
816
1445
  if (this._allPrograms) {
817
1446
  return this._allPrograms;
818
1447
  }
819
- const arr: Program[] = this.programs;
820
- const nexts = this.programs;
821
- for (const next of nexts) {
822
- arr.push(...next.allPrograms);
1448
+ const arr: Program[] = [];
1449
+ const pending = [...this.programs];
1450
+ const visited = new Set<Program>([this]);
1451
+ while (pending.length > 0) {
1452
+ const next = pending.pop()!;
1453
+ if (visited.has(next)) continue;
1454
+ visited.add(next);
1455
+ arr.push(next);
1456
+ const nested = (next as Program & { programs?: Program[] }).programs;
1457
+ pending.push(
1458
+ ...(Array.isArray(nested) ? nested : getValuesWithType(next, Program)),
1459
+ );
823
1460
  }
824
1461
  this._allPrograms = arr;
825
1462
  return this._allPrograms;
@@ -905,6 +1542,7 @@ export abstract class Program<
905
1542
  remote: {
906
1543
  timeout: options?.timeout,
907
1544
  priority: 1,
1545
+ replicate: true,
908
1546
  },
909
1547
  });
910
1548
  if (!bytes) {