@atolis-hq/wake 0.4.104 → 0.4.106

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.
Files changed (161) hide show
  1. package/dist/src/activities/agent/agent-activity.js +10 -0
  2. package/dist/src/activities/contracts/activity.d.ts +28 -0
  3. package/dist/src/activities/contracts/event-schema.d.ts +314 -8
  4. package/dist/src/activities/contracts/event-schema.js +20 -2
  5. package/dist/src/activities/contracts/events.d.ts +10 -0
  6. package/dist/src/activities/contracts/vocabulary.d.ts +2 -0
  7. package/dist/src/activities/contracts/vocabulary.js +2 -0
  8. package/dist/src/activities/index.d.ts +2 -0
  9. package/dist/src/activities/index.js +2 -0
  10. package/dist/src/activities/pr/activity-support.d.ts +1 -1
  11. package/dist/src/activities/pr/activity-support.js +10 -0
  12. package/dist/src/activities/pr/application.js +8 -1
  13. package/dist/src/activities/pr/approve.d.ts +2 -1
  14. package/dist/src/activities/pr/approve.js +33 -11
  15. package/dist/src/activities/pr/check-evidence.d.ts +10 -0
  16. package/dist/src/activities/pr/check-evidence.js +16 -0
  17. package/dist/src/activities/pr/contracts.d.ts +14 -0
  18. package/dist/src/activities/pr/event-data.js +5 -1
  19. package/dist/src/activities/pr/merge.d.ts +2 -1
  20. package/dist/src/activities/pr/merge.js +54 -38
  21. package/dist/src/activities/pr/parent-scope.d.ts +65 -0
  22. package/dist/src/activities/pr/parent-scope.js +24 -0
  23. package/dist/src/activities/pr/parent-target.d.ts +45 -0
  24. package/dist/src/activities/pr/parent-target.js +59 -0
  25. package/dist/src/activities/pr/projection.js +10 -2
  26. package/dist/src/activities/pr/vocabulary.d.ts +8 -0
  27. package/dist/src/activities/pr/vocabulary.js +8 -0
  28. package/dist/src/bootstrap/activity-registry.d.ts +2 -2
  29. package/dist/src/bootstrap/activity-registry.js +3 -3
  30. package/dist/src/bootstrap/composition-root.js +11 -2
  31. package/dist/src/bootstrap/config/root-schema.d.ts +22 -0
  32. package/dist/src/bootstrap/delegation-authority.js +17 -0
  33. package/dist/src/bootstrap/delivery-integration.d.ts +9 -0
  34. package/dist/src/bootstrap/delivery-integration.js +46 -0
  35. package/dist/src/bootstrap/surface-api-delivery.js +52 -0
  36. package/dist/src/bootstrap/version.js +1 -1
  37. package/dist/src/control-plane/application/activation-scheduler-ports.d.ts +5 -1
  38. package/dist/src/control-plane/application/advance-once-dispatch.js +12 -6
  39. package/dist/src/execution/application/candidate-workspaces.d.ts +13 -0
  40. package/dist/src/execution/application/candidate-workspaces.js +75 -0
  41. package/dist/src/execution/application/execution-service.js +37 -11
  42. package/dist/src/execution/application/maintenance-workspaces.d.ts +17 -0
  43. package/dist/src/execution/application/maintenance-workspaces.js +84 -0
  44. package/dist/src/execution/application/run-lifecycle.js +2 -0
  45. package/dist/src/execution/contracts/candidate.d.ts +31 -0
  46. package/dist/src/execution/contracts/candidate.js +40 -0
  47. package/dist/src/execution/contracts/commands.d.ts +4 -0
  48. package/dist/src/execution/contracts/events.d.ts +24 -0
  49. package/dist/src/execution/contracts/events.js +4 -0
  50. package/dist/src/execution/contracts/maintenance.d.ts +36 -0
  51. package/dist/src/execution/contracts/maintenance.js +44 -0
  52. package/dist/src/execution/contracts/repository-assignment.d.ts +5 -0
  53. package/dist/src/execution/contracts/repository-assignment.js +8 -0
  54. package/dist/src/execution/contracts/views.d.ts +4 -0
  55. package/dist/src/execution/contracts/vocabulary.d.ts +5 -0
  56. package/dist/src/execution/contracts/vocabulary.js +4 -0
  57. package/dist/src/execution/contracts/workspace.d.ts +8 -0
  58. package/dist/src/execution/index.d.ts +2 -0
  59. package/dist/src/execution/index.js +2 -0
  60. package/dist/src/execution/infrastructure/workspace/git-source.d.ts +2 -2
  61. package/dist/src/execution/infrastructure/workspace/git-source.js +18 -1
  62. package/dist/src/execution/infrastructure/workspace/git-workspace.d.ts +2 -4
  63. package/dist/src/execution/infrastructure/workspace/git-workspace.js +12 -1
  64. package/dist/src/integrations/application/delegation-outputs.js +1 -1
  65. package/dist/src/integrations/application/delivery-integration-verification.d.ts +13 -0
  66. package/dist/src/integrations/application/delivery-integration-verification.js +68 -0
  67. package/dist/src/integrations/delivery/application/delivery-projector.js +3 -0
  68. package/dist/src/integrations/delivery/application/merged-delivery-evidence.js +9 -1
  69. package/dist/src/integrations/delivery/contracts/views.d.ts +2 -0
  70. package/dist/src/integrations/fake/external-source.d.ts +5 -2
  71. package/dist/src/integrations/fake/external-source.js +12 -2
  72. package/dist/src/integrations/fake/inbound-translator.js +7 -2
  73. package/dist/src/integrations/fake/provider.d.ts +17 -0
  74. package/dist/src/integrations/fake/provider.js +18 -2
  75. package/dist/src/integrations/github/application/pull-request-translation.js +2 -0
  76. package/dist/src/integrations/github/contracts/events.d.ts +3 -1
  77. package/dist/src/integrations/github/contracts/events.js +3 -1
  78. package/dist/src/integrations/github/contracts/payloads.d.ts +23 -0
  79. package/dist/src/integrations/github/infrastructure/check-execution.d.ts +9 -0
  80. package/dist/src/integrations/github/infrastructure/check-execution.js +68 -0
  81. package/dist/src/integrations/github/infrastructure/checkout-revision.d.ts +2 -0
  82. package/dist/src/integrations/github/infrastructure/checkout-revision.js +23 -0
  83. package/dist/src/integrations/github/infrastructure/client.d.ts +2 -0
  84. package/dist/src/integrations/github/infrastructure/client.js +4 -0
  85. package/dist/src/integrations/github/infrastructure/pr-check-subject.d.ts +7 -0
  86. package/dist/src/integrations/github/infrastructure/pr-check-subject.js +77 -0
  87. package/dist/src/integrations/github/infrastructure/pr-evidence.d.ts +6 -3
  88. package/dist/src/integrations/github/infrastructure/pr-evidence.js +1 -1
  89. package/dist/src/integrations/github/infrastructure/pr-source.d.ts +3 -5
  90. package/dist/src/integrations/github/infrastructure/pr-source.js +11 -1
  91. package/dist/src/integrations/github/infrastructure/workflow-run-evidence.d.ts +5 -0
  92. package/dist/src/integrations/github/infrastructure/workflow-run-evidence.js +22 -0
  93. package/dist/src/integrations/index.d.ts +1 -0
  94. package/dist/src/integrations/index.js +1 -0
  95. package/dist/src/orchestration/application/delegated-work.d.ts +5 -0
  96. package/dist/src/orchestration/application/delegated-work.js +10 -0
  97. package/dist/src/orchestration/application/delegation-commands.d.ts +16 -0
  98. package/dist/src/orchestration/application/delivery-coordinator.d.ts +348 -0
  99. package/dist/src/orchestration/application/delivery-coordinator.js +239 -0
  100. package/dist/src/orchestration/application/delivery-facts-reader.d.ts +9 -0
  101. package/dist/src/orchestration/application/delivery-facts-reader.js +47 -0
  102. package/dist/src/orchestration/application/delivery-integration-reader.d.ts +9 -0
  103. package/dist/src/orchestration/application/delivery-integration-reader.js +23 -0
  104. package/dist/src/orchestration/application/delivery-integration-service.d.ts +50 -0
  105. package/dist/src/orchestration/application/delivery-integration-service.js +228 -0
  106. package/dist/src/orchestration/application/delivery-preparation.d.ts +16 -0
  107. package/dist/src/orchestration/application/delivery-preparation.js +105 -0
  108. package/dist/src/orchestration/application/delivery-sources.d.ts +10 -0
  109. package/dist/src/orchestration/application/delivery-sources.js +41 -0
  110. package/dist/src/orchestration/application/orchestration-repository.d.ts +3 -1
  111. package/dist/src/orchestration/application/orchestration-repository.js +10 -1
  112. package/dist/src/orchestration/application/orchestration-service.d.ts +341 -2
  113. package/dist/src/orchestration/application/orchestration-service.js +86 -4
  114. package/dist/src/orchestration/contracts/config.d.ts +22 -0
  115. package/dist/src/orchestration/contracts/config.js +13 -1
  116. package/dist/src/orchestration/contracts/delegation-ports.d.ts +4 -0
  117. package/dist/src/orchestration/contracts/delegation.d.ts +13 -1
  118. package/dist/src/orchestration/contracts/delegation.js +5 -0
  119. package/dist/src/orchestration/contracts/delivery-ports.d.ts +53 -0
  120. package/dist/src/orchestration/contracts/delivery-ports.js +1 -0
  121. package/dist/src/orchestration/contracts/delivery.d.ts +310 -0
  122. package/dist/src/orchestration/contracts/delivery.js +186 -0
  123. package/dist/src/orchestration/contracts/event-decoder.js +14 -1
  124. package/dist/src/orchestration/contracts/event-factory.js +8 -0
  125. package/dist/src/orchestration/contracts/events.d.ts +10 -0
  126. package/dist/src/orchestration/contracts/events.js +4 -0
  127. package/dist/src/orchestration/contracts/views.d.ts +3 -0
  128. package/dist/src/orchestration/contracts/vocabulary.d.ts +90 -0
  129. package/dist/src/orchestration/contracts/vocabulary.js +82 -0
  130. package/dist/src/orchestration/domain/compile-diagnostics.d.ts +1 -1
  131. package/dist/src/orchestration/domain/compile-diagnostics.js +5 -0
  132. package/dist/src/orchestration/domain/compiler.js +2 -0
  133. package/dist/src/orchestration/domain/delivery-candidate.d.ts +9 -0
  134. package/dist/src/orchestration/domain/delivery-candidate.js +105 -0
  135. package/dist/src/orchestration/domain/delivery-facts.d.ts +89 -0
  136. package/dist/src/orchestration/domain/delivery-facts.js +66 -0
  137. package/dist/src/orchestration/domain/delivery-integration-policy.d.ts +7 -0
  138. package/dist/src/orchestration/domain/delivery-integration-policy.js +15 -0
  139. package/dist/src/orchestration/domain/delivery-integration.d.ts +54 -0
  140. package/dist/src/orchestration/domain/delivery-integration.js +144 -0
  141. package/dist/src/orchestration/domain/delivery-qa.d.ts +33 -0
  142. package/dist/src/orchestration/domain/delivery-qa.js +97 -0
  143. package/dist/src/orchestration/domain/delivery-replacement.d.ts +9 -0
  144. package/dist/src/orchestration/domain/delivery-replacement.js +54 -0
  145. package/dist/src/orchestration/domain/delivery-selection.d.ts +17 -0
  146. package/dist/src/orchestration/domain/delivery-selection.js +132 -0
  147. package/dist/src/orchestration/domain/delivery-workflow-policy.d.ts +6 -0
  148. package/dist/src/orchestration/domain/delivery-workflow-policy.js +32 -0
  149. package/dist/src/orchestration/domain/operator-retry-policy.js +24 -13
  150. package/dist/src/orchestration/domain/workflow-instance-events.d.ts +1 -0
  151. package/dist/src/orchestration/domain/workflow-instance-events.js +12 -0
  152. package/dist/src/orchestration/index.d.ts +3 -0
  153. package/dist/src/orchestration/index.js +1 -0
  154. package/dist/src/surfaces/api/contracts/transport-values.js +1 -0
  155. package/dist/src/surfaces/api/contracts/work.d.ts +42 -0
  156. package/dist/src/surfaces/api/presenters/execution.js +1 -0
  157. package/dist/src/surfaces/mcp/delegation.js +36 -1
  158. package/dist/src/surfaces/web-assets/assets/index-ih1h3dxC.js +1192 -0
  159. package/dist/src/surfaces/web-assets/index.html +1 -1
  160. package/package.json +1 -1
  161. package/dist/src/surfaces/web-assets/assets/index-C5R-aWzH.js +0 -1192
@@ -0,0 +1,89 @@
1
+ import type { DelegationReservation, DelegationResult } from '../contracts/delegation.js';
2
+ import { DeliveryRejectionError, type DeliveryCandidate, type DeliveryMaintenance, type DeliveryOutputKey, type DeliveryQa, type DeliverySelection } from '../contracts/delivery.js';
3
+ import type { DeliveryRejection } from '../contracts/vocabulary.js';
4
+ export type Output = DelegationResult['outputs'][number];
5
+ export type Child = DelegationReservation['children'][number];
6
+ export type ChangeReference = Extract<Output['reference'], {
7
+ readonly repositoryResourceId: string;
8
+ }>;
9
+ /** Everything the delivery rules read; all of it is journal-derived. */
10
+ export interface DeliveryFacts {
11
+ readonly reservations: readonly DelegationReservation[];
12
+ readonly results: readonly DelegationResult[];
13
+ /** Outputs each child consumed as prerequisites, by child WorkItem. */
14
+ readonly consumed: ReadonlyMap<string, readonly Output[]>;
15
+ readonly selections: readonly DeliverySelection[];
16
+ readonly candidates: readonly DeliveryCandidate[];
17
+ readonly qa: readonly DeliveryQa[];
18
+ /** Agent maintenance of selected changes, oldest first; each is a new immutable subject. */
19
+ readonly maintenance: readonly DeliveryMaintenance[];
20
+ }
21
+ export declare const outputKey: (key: DeliveryOutputKey) => string;
22
+ export declare const entryKey: (entry: {
23
+ cohortId: string;
24
+ assignmentId: string;
25
+ }, name: string) => string;
26
+ export declare const reject: (code: DeliveryRejection, message: string) => DeliveryRejectionError;
27
+ export declare const isChange: (output: Output) => output is Output & {
28
+ reference: ChangeReference;
29
+ };
30
+ /**
31
+ * The latest selection with each change at its newest maintained subject. The recorded selection
32
+ * and every earlier subject stay in the journal; nothing else reads a stale head or base.
33
+ */
34
+ export declare function currentSelection(facts: DeliveryFacts): DeliverySelection | undefined;
35
+ export interface Requirement {
36
+ readonly cohortId: string;
37
+ readonly assignmentId: string;
38
+ readonly outputName: string;
39
+ readonly child: Child;
40
+ readonly criteria: readonly string[];
41
+ }
42
+ /** Original required assignments: those not themselves declared as a replacement. */
43
+ export declare function requirements(reservations: readonly DelegationReservation[]): Requirement[];
44
+ export declare function childOf(reservations: readonly DelegationReservation[], id: string): {
45
+ cohortId: string;
46
+ child: {
47
+ assignmentId: string;
48
+ objective: string;
49
+ criteria: string[];
50
+ workflowName: import("../index.js").WorkflowName;
51
+ workflowFingerprint: string;
52
+ context: {
53
+ workItemId: import("../../work/index.js").WorkItemId;
54
+ revisionId: string;
55
+ }[];
56
+ outputs: ({
57
+ name: string;
58
+ path: string;
59
+ } | {
60
+ name: string;
61
+ kind: "change";
62
+ requireReview?: boolean | undefined;
63
+ requireChecks?: boolean | undefined;
64
+ })[];
65
+ workItemId: import("../../work/index.js").WorkItemId;
66
+ workflowInstanceId: import("../index.js").WorkflowInstanceId;
67
+ grantId: string;
68
+ repositoryResourceIds?: string[] | undefined;
69
+ prerequisites?: {
70
+ assignmentId: string;
71
+ output: string;
72
+ condition: "accepted-output" | "pushed-change" | "delivery-ready" | "merged-change";
73
+ cohortId?: string | undefined;
74
+ useAsBase?: boolean | undefined;
75
+ }[] | undefined;
76
+ replaces?: {
77
+ cohortId: string;
78
+ assignmentId: string;
79
+ } | undefined;
80
+ repository?: {
81
+ resourceId: string;
82
+ sourceRef: string;
83
+ pullRequestBase: string;
84
+ sourceRevision: string;
85
+ } | undefined;
86
+ prerequisiteWorkItemIds?: import("../../work/index.js").WorkItemId[] | undefined;
87
+ };
88
+ } | undefined;
89
+ export declare function qualifying(facts: DeliveryFacts, key: DeliveryOutputKey): Output | undefined;
@@ -0,0 +1,66 @@
1
+ import { DeliveryRejectionError, } from '../contracts/delivery.js';
2
+ export const outputKey = (key) => `${key.childWorkItemId}/${key.outputName}`;
3
+ export const entryKey = (entry, name) => `${entry.cohortId}/${entry.assignmentId}/${name}`;
4
+ export const reject = (code, message) => new DeliveryRejectionError(code, message);
5
+ export const isChange = (output) => 'repositoryResourceId' in output.reference;
6
+ /**
7
+ * The latest selection with each change at its newest maintained subject. The recorded selection
8
+ * and every earlier subject stay in the journal; nothing else reads a stale head or base.
9
+ */
10
+ export function currentSelection(facts) {
11
+ const selection = facts.selections.at(-1);
12
+ if (selection === undefined || facts.maintenance.length === 0)
13
+ return selection;
14
+ return {
15
+ ...selection,
16
+ entries: selection.entries.map((entry) => {
17
+ const latest = facts.maintenance
18
+ .filter((item) => item.target.childWorkItemId === entry.childWorkItemId &&
19
+ item.target.outputName === entry.output.name)
20
+ .at(-1);
21
+ if (latest === undefined || !isChange(entry.output))
22
+ return entry;
23
+ return {
24
+ ...entry,
25
+ output: {
26
+ ...entry.output,
27
+ reference: {
28
+ ...entry.output.reference,
29
+ revision: latest.current.revision,
30
+ pullRequestBase: latest.current.pullRequestBase,
31
+ runId: latest.producer.runId,
32
+ ...(latest.current.baseRevision === undefined
33
+ ? {}
34
+ : { baseRevision: latest.current.baseRevision }),
35
+ },
36
+ },
37
+ };
38
+ }),
39
+ };
40
+ }
41
+ /** Original required assignments: those not themselves declared as a replacement. */
42
+ export function requirements(reservations) {
43
+ return reservations.flatMap((reservation) => reservation.children
44
+ .filter((child) => child.replaces === undefined)
45
+ .flatMap((child) => child.outputs.map((output) => ({
46
+ cohortId: reservation.cohortId,
47
+ assignmentId: child.assignmentId,
48
+ outputName: output.name,
49
+ child,
50
+ criteria: child.criteria,
51
+ }))));
52
+ }
53
+ export function childOf(reservations, id) {
54
+ for (const reservation of reservations) {
55
+ const child = reservation.children.find((entry) => entry.workItemId === id);
56
+ if (child !== undefined)
57
+ return { cohortId: reservation.cohortId, child };
58
+ }
59
+ return undefined;
60
+ }
61
+ export function qualifying(facts, key) {
62
+ return facts.results
63
+ .filter((result) => result.childWorkItemId === key.childWorkItemId)
64
+ .flatMap((result) => result.outputs)
65
+ .find((output) => output.name === key.outputName);
66
+ }
@@ -0,0 +1,7 @@
1
+ import { type ParentActionRequest } from '../../activities/index.js';
2
+ import type { DeliveryOutputKey } from '../contracts/delivery.js';
3
+ import type { DeliveryFacts } from './delivery-facts.js';
4
+ export declare function targetRequirements(facts: DeliveryFacts, key: DeliveryOutputKey, action: ParentActionRequest['action']): {
5
+ requireReview: boolean;
6
+ requireChecks: boolean;
7
+ };
@@ -0,0 +1,15 @@
1
+ import { ParentActionKind } from '../../activities/index.js';
2
+ import { DelegationOutputKind } from '../contracts/vocabulary.js';
3
+ export function targetRequirements(facts, key, action) {
4
+ const required = facts.reservations
5
+ .flatMap((reservation) => reservation.children)
6
+ .find((child) => child.workItemId === key.childWorkItemId)
7
+ ?.outputs.find((output) => output.name === key.outputName);
8
+ const merging = action === ParentActionKind.Merge;
9
+ if (required !== undefined && 'kind' in required && required.kind === DelegationOutputKind.Change)
10
+ return {
11
+ requireReview: merging && (required.requireReview ?? true),
12
+ requireChecks: merging && (required.requireChecks ?? true),
13
+ };
14
+ return { requireReview: merging, requireChecks: merging };
15
+ }
@@ -0,0 +1,54 @@
1
+ import { PullRequestMergeability, PullRequestState } from '../../activities/index.js';
2
+ import type { WorkItemId } from '../../work/index.js';
3
+ import type { DeliveryOutputKey } from '../contracts/delivery.js';
4
+ import { BaseMovement, IntegrationState, MaintenanceReason } from '../contracts/vocabulary.js';
5
+ import { type DeliveryFacts } from './delivery-facts.js';
6
+ /** The provider facts the integration decision needs; never inferred from agent claims. */
7
+ export interface PullRequestObservation {
8
+ readonly state: PullRequestState;
9
+ readonly headRevision: string;
10
+ readonly baseRevision: string;
11
+ readonly mergeRevision?: string | undefined;
12
+ readonly mergeability?: PullRequestMergeability | undefined;
13
+ }
14
+ export interface IntegrationTarget {
15
+ readonly output: DeliveryOutputKey;
16
+ /** The pull request's primary owner: it never changes and is never the requesting parent. */
17
+ readonly ownerWorkItemId: WorkItemId;
18
+ readonly resourceId: string;
19
+ readonly repositoryResourceId: string;
20
+ readonly branch: string;
21
+ readonly pullRequestBase: string;
22
+ /** The selected subject's head; a merged change is only verified at exactly this head. */
23
+ readonly revision: string;
24
+ /** 0 targets the integration branch; each stacked layer sits one above the change it targets. */
25
+ readonly layer: number;
26
+ readonly state: IntegrationState;
27
+ readonly maintenance?: MaintenanceReason;
28
+ readonly baseMovement: BaseMovement;
29
+ /** Only the targets that need fresh review, checks and QA; unrelated subjects keep theirs. */
30
+ readonly evidenceAffected: boolean;
31
+ /** A merged change whose merged head is not the subject that was reviewed and tested. */
32
+ readonly unverifiedMerge: boolean;
33
+ readonly detail?: string;
34
+ }
35
+ /** What completion needs to know about integration. */
36
+ export interface IntegrationOutcome {
37
+ readonly complete: boolean;
38
+ readonly summary: string;
39
+ }
40
+ export interface IntegrationAssessment extends IntegrationOutcome {
41
+ readonly targets: readonly IntegrationTarget[];
42
+ /** The next planned merge: the first unmerged change, and only when it is ready. */
43
+ readonly next: IntegrationTarget | null;
44
+ /** The first unmerged change when it cannot proceed yet. */
45
+ readonly blocking: IntegrationTarget | null;
46
+ }
47
+ export declare const known: (value: string | undefined) => value is string;
48
+ /**
49
+ * Derives integration progress from the selected subjects and actual provider state. Partial
50
+ * progress is whatever the provider shows merged; there is no separate progress record, so a
51
+ * restart recomputes the same answer, and ordinary merges never count as defect corrections.
52
+ */
53
+ export declare function assessIntegration(facts: DeliveryFacts, observations: ReadonlyMap<string, PullRequestObservation>, held: ReadonlyMap<string, string>): IntegrationAssessment;
54
+ export declare const sameRevision: (a: string, b: string) => boolean;
@@ -0,0 +1,144 @@
1
+ import { PullRequestMergeability, PullRequestState } from '../../activities/index.js';
2
+ import { BaseMovement, IntegrationState, MaintenanceReason } from '../contracts/vocabulary.js';
3
+ import { currentSelection, isChange, outputKey, } from './delivery-facts.js';
4
+ /** Providers report an unobserved revision with the shared unknown placeholder, not by omitting it. */
5
+ const unobservedRevision = PullRequestMergeability.Unknown;
6
+ export const known = (value) => value !== undefined && value !== '' && value !== unobservedRevision;
7
+ /**
8
+ * Derives integration progress from the selected subjects and actual provider state. Partial
9
+ * progress is whatever the provider shows merged; there is no separate progress record, so a
10
+ * restart recomputes the same answer, and ordinary merges never count as defect corrections.
11
+ */
12
+ export function assessIntegration(facts, observations, held) {
13
+ const changes = (currentSelection(facts)?.entries ?? []).flatMap((entry) => isChange(entry.output)
14
+ ? [
15
+ {
16
+ output: { childWorkItemId: entry.childWorkItemId, outputName: entry.output.name },
17
+ reference: entry.output.reference,
18
+ },
19
+ ]
20
+ : []);
21
+ const observed = (change) => observations.get(change.reference.resourceId);
22
+ const merged = (change) => observed(change)?.state === PullRequestState.Merged;
23
+ const lowerOf = (change) => changes.find((candidate) => candidate !== change &&
24
+ candidate.reference.repositoryResourceId === change.reference.repositoryResourceId &&
25
+ candidate.reference.branch === change.reference.pullRequestBase);
26
+ const layerOf = (change, depth = 0) => {
27
+ const lower = lowerOf(change);
28
+ return lower === undefined || depth > changes.length ? 0 : layerOf(lower, depth + 1) + 1;
29
+ };
30
+ const targets = changes
31
+ .map((change) => {
32
+ const lower = lowerOf(change);
33
+ const plannedBase = changes.some((other) => other !== change &&
34
+ other.reference.repositoryResourceId === change.reference.repositoryResourceId &&
35
+ other.reference.pullRequestBase === change.reference.pullRequestBase &&
36
+ merged(other) &&
37
+ known(observed(change)?.baseRevision) &&
38
+ known(observed(other)?.mergeRevision) &&
39
+ sameRevision(observed(change).baseRevision, observed(other).mergeRevision));
40
+ return decide(change, {
41
+ observation: observed(change),
42
+ held: held.get(change.output.childWorkItemId),
43
+ lower: lower === undefined ? undefined : { merged: merged(lower), change: lower },
44
+ plannedBase,
45
+ layer: layerOf(change),
46
+ });
47
+ })
48
+ .sort((a, b) => a.repositoryResourceId.localeCompare(b.repositoryResourceId) ||
49
+ a.layer - b.layer ||
50
+ outputKey(a.output).localeCompare(outputKey(b.output)));
51
+ const unmerged = targets.filter((target) => target.state !== IntegrationState.Merged);
52
+ const first = unmerged[0] ?? null;
53
+ const next = first?.state === IntegrationState.Ready ? first : null;
54
+ const complete = changes.length > 0 && unmerged.length === 0 && targets.every((t) => !t.unverifiedMerge);
55
+ return {
56
+ targets,
57
+ next,
58
+ blocking: first !== null && next === null ? first : null,
59
+ complete,
60
+ summary: summarize(targets, next, first, complete),
61
+ };
62
+ }
63
+ function decide(change, input) {
64
+ const { reference } = change;
65
+ const base = {
66
+ output: change.output,
67
+ ownerWorkItemId: reference.workItemId,
68
+ resourceId: reference.resourceId,
69
+ repositoryResourceId: reference.repositoryResourceId,
70
+ branch: reference.branch,
71
+ pullRequestBase: reference.pullRequestBase,
72
+ revision: reference.revision,
73
+ layer: input.layer,
74
+ baseMovement: BaseMovement.None,
75
+ evidenceAffected: false,
76
+ unverifiedMerge: false,
77
+ };
78
+ const { observation } = input;
79
+ if (observation?.state === PullRequestState.Merged)
80
+ return {
81
+ ...base,
82
+ state: IntegrationState.Merged,
83
+ unverifiedMerge: !sameRevision(observation.headRevision, reference.revision),
84
+ };
85
+ if (input.held !== undefined)
86
+ return { ...base, state: IntegrationState.Held, detail: input.held };
87
+ if (observation === undefined)
88
+ return { ...base, state: IntegrationState.Unobserved };
89
+ if (observation.state === PullRequestState.Closed)
90
+ return { ...base, state: IntegrationState.Closed };
91
+ const movement = baseMovement(reference, observation, input.plannedBase);
92
+ const maintain = (reason, detail) => ({
93
+ ...base,
94
+ baseMovement: movement,
95
+ state: IntegrationState.MaintenanceRequired,
96
+ maintenance: reason,
97
+ evidenceAffected: true,
98
+ detail,
99
+ });
100
+ // Another writer changed the branch: the reviewed and tested subject no longer exists.
101
+ if (!sameRevision(observation.headRevision, reference.revision))
102
+ return maintain(MaintenanceReason.HeadMoved, `the provider head ${observation.headRevision} is not the recorded subject ${reference.revision}`);
103
+ if (input.lower !== undefined) {
104
+ if (!input.lower.merged)
105
+ return {
106
+ ...base,
107
+ baseMovement: movement,
108
+ state: IntegrationState.AwaitingLowerLayer,
109
+ detail: `waiting for ${input.lower.change.output.childWorkItemId}`,
110
+ };
111
+ return maintain(MaintenanceReason.Retarget, `${input.lower.change.reference.branch} merged; retarget ${reference.branch} to the integration branch`);
112
+ }
113
+ if (observation.mergeability === PullRequestMergeability.Conflicting)
114
+ return maintain(MaintenanceReason.Conflict, 'the provider reports conflicts with the base');
115
+ if (movement === BaseMovement.PlannedProgress)
116
+ return maintain(MaintenanceReason.BaseMoved, 'a selected sibling merged into the base; refresh the changed base subject before continuing');
117
+ if (movement === BaseMovement.Unrelated)
118
+ return maintain(MaintenanceReason.BaseMoved, 'the base moved outside this delivery, so the tested combination is unproven');
119
+ return { ...base, baseMovement: movement, state: IntegrationState.Ready };
120
+ }
121
+ /** Match the actual integration commit, never assume a merged source head became the base. */
122
+ function baseMovement(reference, observation, plannedBase) {
123
+ if (!known(reference.baseRevision) || !known(observation.baseRevision))
124
+ return BaseMovement.None;
125
+ if (sameRevision(reference.baseRevision, observation.baseRevision))
126
+ return BaseMovement.None;
127
+ return plannedBase ? BaseMovement.PlannedProgress : BaseMovement.Unrelated;
128
+ }
129
+ export const sameRevision = (a, b) => a.toLowerCase() === b.toLowerCase();
130
+ function summarize(targets, next, first, complete) {
131
+ if (targets.length === 0)
132
+ return 'no selected changes to integrate';
133
+ const mergedCount = targets.filter((target) => target.state === IntegrationState.Merged).length;
134
+ const progress = `${mergedCount}/${targets.length} selected changes merged`;
135
+ if (complete)
136
+ return progress;
137
+ if (targets.some((target) => target.unverifiedMerge))
138
+ return `${progress}; a merged head differs from the reviewed and tested subject`;
139
+ if (next !== null)
140
+ return `${progress}; next is ${outputKey(next.output)}`;
141
+ if (first === null)
142
+ return progress;
143
+ return `${progress}; ${outputKey(first.output)} is ${first.state}${first.maintenance === undefined ? '' : ` (${first.maintenance})`}`;
144
+ }
@@ -0,0 +1,33 @@
1
+ import type { DeliveryCandidate, DeliveryQa, DeliveryQaCommand } from '../contracts/delivery.js';
2
+ import { DeliveryCompletion } from '../contracts/vocabulary.js';
3
+ import { type DeliveryFacts } from './delivery-facts.js';
4
+ import type { IntegrationOutcome } from './delivery-integration.js';
5
+ /** The exact repository and revision set QA must have checked. */
6
+ export declare const revisionSet: (items: readonly {
7
+ resourceId: string;
8
+ revision: string;
9
+ }[]) => string[];
10
+ /** QA can only vouch for the candidate's own revisions, and never passes without an environment. */
11
+ export declare function assertQa(facts: DeliveryFacts, command: DeliveryQaCommand): DeliveryQa;
12
+ export interface DeliveryState {
13
+ readonly selectionRevision: number;
14
+ readonly stale: readonly string[];
15
+ readonly candidate: DeliveryCandidate | null;
16
+ /** The latest candidate belongs to the current selection and nothing in it is stale. */
17
+ readonly candidateCurrent: boolean;
18
+ readonly qa: DeliveryQa | null;
19
+ /** The latest QA is for the current candidate; older verdicts stay historical. */
20
+ readonly qaEffective: boolean;
21
+ readonly repair: {
22
+ readonly failedRounds: number;
23
+ readonly exhausted: boolean;
24
+ readonly unresolvedFindings: readonly string[];
25
+ };
26
+ }
27
+ export declare function deliveryState(facts: DeliveryFacts): DeliveryState;
28
+ export interface CompletionDecision {
29
+ readonly complete: boolean;
30
+ readonly reason?: string;
31
+ }
32
+ /** DC-24 handoff boundary: QA approval finishes a QA-approved parent but never a merge-required one. */
33
+ export declare function completionDecision(state: DeliveryState, mode: DeliveryCompletion, integration?: IntegrationOutcome): CompletionDecision;
@@ -0,0 +1,97 @@
1
+ import { isDeepStrictEqual } from 'node:util';
2
+ import { DeliveryCompletion, DeliveryRejection, QaVerdict } from '../contracts/vocabulary.js';
3
+ import { currentSelection, entryKey, isChange, outputKey, reject, requirements, } from './delivery-facts.js';
4
+ import { staleEntries } from './delivery-selection.js';
5
+ /** The exact repository and revision set QA must have checked. */
6
+ export const revisionSet = (items) => items.map((item) => `${item.resourceId}@${item.revision.toLowerCase()}`).sort();
7
+ /** QA can only vouch for the candidate's own revisions, and never passes without an environment. */
8
+ export function assertQa(facts, command) {
9
+ const candidate = facts.candidates.find((entry) => entry.candidateId === command.candidateId);
10
+ if (candidate === undefined)
11
+ throw reject(DeliveryRejection.UnknownCandidate, `Unknown candidate ${command.candidateId}`);
12
+ if (!isDeepStrictEqual(revisionSet(command.revisions), revisionSet(candidate.repositories)))
13
+ throw reject(DeliveryRejection.RevisionMismatch, 'QA must check exactly the candidate repository revisions; testing main or another candidate cannot satisfy the gate');
14
+ if (!command.environment.available && command.verdict !== QaVerdict.Blocked)
15
+ throw reject(DeliveryRejection.InvalidVerdict, 'An unavailable environment must be reported as blocked');
16
+ if (command.verdict === QaVerdict.Pass)
17
+ assertPass(candidate, command);
18
+ if (command.verdict === QaVerdict.Fail && command.findings.length === 0)
19
+ throw reject(DeliveryRejection.InvalidVerdict, 'A failing verdict must state its findings');
20
+ return { ...command };
21
+ }
22
+ function assertPass(candidate, command) {
23
+ if (!command.environment.available)
24
+ throw reject(DeliveryRejection.InvalidVerdict, 'An unavailable environment is a blocker, never a pass');
25
+ if (command.findings.length > 0)
26
+ throw reject(DeliveryRejection.InvalidVerdict, 'A passing verdict cannot carry findings');
27
+ if (candidate.recipe !== undefined && command.environment.recipe !== candidate.recipe)
28
+ throw reject(DeliveryRejection.InvalidVerdict, 'QA must run the configured environment and test recipe');
29
+ }
30
+ export function deliveryState(facts) {
31
+ const current = currentSelection(facts);
32
+ const stale = [...staleEntries(facts)];
33
+ const candidate = facts.candidates.at(-1) ?? null;
34
+ const candidateCurrent = isCandidateCurrent(facts, current, candidate, stale);
35
+ const qa = facts.qa.filter((entry) => entry.candidateId === candidate?.candidateId).at(-1) ?? null;
36
+ const qaEffective = qa !== null && qa.runId !== undefined && qa.activationId !== undefined && candidateCurrent;
37
+ return {
38
+ selectionRevision: current?.revision ?? 0,
39
+ stale,
40
+ candidate,
41
+ candidateCurrent,
42
+ qa,
43
+ qaEffective,
44
+ repair: {
45
+ failedRounds: facts.qa.filter((entry) => entry.verdict === QaVerdict.Fail).length,
46
+ exhausted: facts.qa.at(-1)?.exhausted === true,
47
+ unresolvedFindings: qaEffective && qa.verdict !== QaVerdict.Pass ? qa.findings : [],
48
+ },
49
+ };
50
+ }
51
+ /** DC-24 handoff boundary: QA approval finishes a QA-approved parent but never a merge-required one. */
52
+ export function completionDecision(state, mode, integration) {
53
+ if (state.stale.length > 0)
54
+ return {
55
+ complete: false,
56
+ reason: `Stale results need reverification: ${state.stale.join(', ')}`,
57
+ };
58
+ if (state.candidate === null || !state.candidateCurrent)
59
+ return { complete: false, reason: 'No current candidate has been recorded for the selection' };
60
+ if (state.qa === null || !state.qaEffective)
61
+ return { complete: false, reason: 'The current candidate has no QA result' };
62
+ if (state.qa.verdict !== QaVerdict.Pass)
63
+ return { complete: false, reason: `QA verdict is ${state.qa.verdict}` };
64
+ if (mode === DeliveryCompletion.MergeRequired && integration?.complete !== true)
65
+ return {
66
+ complete: false,
67
+ reason: `Governed integration is required and its gates are not satisfied: ${integration?.summary ?? 'integration state is unavailable'}`,
68
+ };
69
+ return { complete: true };
70
+ }
71
+ /** A maintained or replaced change makes any candidate built from its earlier subject historical. */
72
+ function subjectsCurrent(current, candidate) {
73
+ return (candidate.subjects ?? []).every((subject) => {
74
+ const entry = current.entries.find((item) => item.childWorkItemId === subject.childWorkItemId && item.output.name === subject.outputName);
75
+ return (entry !== undefined &&
76
+ isChange(entry.output) &&
77
+ entry.output.reference.revision.toLowerCase() === subject.revision.toLowerCase() &&
78
+ entry.output.reference.pullRequestBase === subject.pullRequestBase &&
79
+ (entry.output.reference.baseRevision ?? '').toLowerCase() ===
80
+ (subject.baseRevision ?? '').toLowerCase());
81
+ });
82
+ }
83
+ function isCandidateCurrent(facts, current, candidate, stale) {
84
+ return (candidate !== null &&
85
+ current !== undefined &&
86
+ candidate.selectionRevision === current?.revision &&
87
+ stale.length === 0 &&
88
+ subjectsCurrent(current, candidate) &&
89
+ legacySubjectsCurrent(facts, candidate) &&
90
+ requirements(facts.reservations).every((requirement) => current.entries.some((entry) => entryKey(entry, entry.output.name) === entryKey(requirement, requirement.outputName))));
91
+ }
92
+ function legacySubjectsCurrent(facts, candidate) {
93
+ if (candidate.subjects !== undefined)
94
+ return true;
95
+ const contributions = new Set(candidate.repositories.flatMap((repository) => repository.contributions.map(outputKey)));
96
+ return !facts.maintenance.some((item) => contributions.has(outputKey(item.target)));
97
+ }
@@ -0,0 +1,9 @@
1
+ import type { DelegatedAssignment } from '../contracts/delegation.js';
2
+ import { type Child, type DeliveryFacts } from './delivery-facts.js';
3
+ /** The original must be a required assignment of this delivery, never another replacement. */
4
+ export declare function originalOf(facts: DeliveryFacts, replaces: NonNullable<DelegatedAssignment['replaces']>): Child;
5
+ /**
6
+ * A corrective child keeps the original acceptance criteria, repository and outputs. When the
7
+ * original contribution is unmerged it must be the starting point, aimed at the intended base.
8
+ */
9
+ export declare function assertCriteriaPreserving(facts: DeliveryFacts, original: Child, assignment: DelegatedAssignment): void;
@@ -0,0 +1,54 @@
1
+ import { DelegationConflictError } from '../contracts/delegation.js';
2
+ import { DelegationConflictCode } from '../contracts/vocabulary.js';
3
+ import { isChange } from './delivery-facts.js';
4
+ const invalid = (message) => new DelegationConflictError(DelegationConflictCode.ReplacementInvalid, message);
5
+ /** The original must be a required assignment of this delivery, never another replacement. */
6
+ export function originalOf(facts, replaces) {
7
+ const original = facts.reservations
8
+ .filter((reservation) => reservation.cohortId === replaces.cohortId)
9
+ .flatMap((reservation) => reservation.children)
10
+ .find((child) => child.assignmentId === replaces.assignmentId && child.replaces === undefined);
11
+ if (original === undefined)
12
+ throw invalid('A replacement must name an original required assignment of this delivery');
13
+ return original;
14
+ }
15
+ /**
16
+ * A corrective child keeps the original acceptance criteria, repository and outputs. When the
17
+ * original contribution is unmerged it must be the starting point, aimed at the intended base.
18
+ */
19
+ export function assertCriteriaPreserving(facts, original, assignment) {
20
+ if (!original.criteria.every((criterion) => assignment.criteria.includes(criterion)))
21
+ throw invalid('A replacement must preserve every original acceptance criterion');
22
+ if (original.repository?.resourceId !== assignment.repository?.resourceId)
23
+ throw invalid('A replacement must target the original repository');
24
+ assertOutputsProvided(original, assignment);
25
+ const unmerged = facts.results
26
+ .filter((entry) => entry.childWorkItemId === original.workItemId)
27
+ .flatMap((entry) => entry.outputs.filter(isChange))
28
+ .map((output) => output.reference)
29
+ .filter((reference) => reference.merged !== true);
30
+ for (const reference of unmerged)
31
+ assertCarriesContribution(assignment, reference);
32
+ }
33
+ function assertOutputsProvided(original, assignment) {
34
+ for (const output of original.outputs) {
35
+ const counterpart = assignment.outputs.find((entry) => entry.name === output.name);
36
+ if (counterpart === undefined || 'kind' in output !== 'kind' in counterpart)
37
+ throw invalid(`A replacement must provide the original output ${output.name}`);
38
+ if ('kind' in output && 'kind' in counterpart)
39
+ assertChangeRequirements(output, counterpart);
40
+ }
41
+ }
42
+ function assertCarriesContribution(assignment, reference) {
43
+ const repository = assignment.repository;
44
+ if (repository?.sourceRevision !== reference.revision)
45
+ throw invalid(`A replacement must start from the unmerged contribution ${reference.branch}@${reference.revision}`);
46
+ if (repository.pullRequestBase !== reference.pullRequestBase)
47
+ throw invalid(`A replacement must target the intended integration branch ${reference.pullRequestBase}`);
48
+ }
49
+ function assertChangeRequirements(original, replacement) {
50
+ if ((original.requireReview ?? true) && !(replacement.requireReview ?? true))
51
+ throw invalid('A replacement must preserve the original review requirement');
52
+ if ((original.requireChecks ?? true) && !(replacement.requireChecks ?? true))
53
+ throw invalid('A replacement must preserve the original checks requirement');
54
+ }
@@ -0,0 +1,17 @@
1
+ import type { DeliverySelection, DeliverySelectionCommand } from '../contracts/delivery.js';
2
+ import { type DeliveryFacts } from './delivery-facts.js';
3
+ /**
4
+ * Validates a complete selection against the current one and the original requirements.
5
+ * An omitted requirement is never a waiver: every original output must stay covered by its own
6
+ * qualifying result or an authorized, criteria-preserving replacement that names the output
7
+ * currently selected.
8
+ */
9
+ export declare function reviseSelection(facts: DeliveryFacts, command: DeliverySelectionCommand): {
10
+ readonly selection: DeliverySelection;
11
+ readonly replay: boolean;
12
+ };
13
+ /**
14
+ * Selected results whose upstream input was replaced. A superseded output makes every consumer
15
+ * stale, transitively; unrelated evidence is untouched and old facts stay in the history.
16
+ */
17
+ export declare function staleEntries(facts: DeliveryFacts): ReadonlySet<string>;