@atolis-hq/wake 0.4.105 → 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 (128) hide show
  1. package/dist/src/activities/agent/agent-activity.js +7 -0
  2. package/dist/src/activities/contracts/activity.d.ts +12 -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 +6 -0
  32. package/dist/src/bootstrap/delivery-integration.d.ts +9 -0
  33. package/dist/src/bootstrap/delivery-integration.js +46 -0
  34. package/dist/src/bootstrap/surface-api-delivery.js +27 -0
  35. package/dist/src/bootstrap/version.js +1 -1
  36. package/dist/src/control-plane/application/activation-scheduler-ports.d.ts +3 -1
  37. package/dist/src/control-plane/application/advance-once-dispatch.js +10 -6
  38. package/dist/src/execution/application/execution-service.js +10 -0
  39. package/dist/src/execution/application/maintenance-workspaces.d.ts +17 -0
  40. package/dist/src/execution/application/maintenance-workspaces.js +84 -0
  41. package/dist/src/execution/application/run-lifecycle.js +1 -0
  42. package/dist/src/execution/contracts/commands.d.ts +2 -0
  43. package/dist/src/execution/contracts/events.d.ts +13 -0
  44. package/dist/src/execution/contracts/events.js +2 -0
  45. package/dist/src/execution/contracts/maintenance.d.ts +36 -0
  46. package/dist/src/execution/contracts/maintenance.js +44 -0
  47. package/dist/src/execution/contracts/views.d.ts +2 -0
  48. package/dist/src/execution/contracts/workspace.d.ts +2 -0
  49. package/dist/src/execution/index.d.ts +1 -0
  50. package/dist/src/execution/index.js +1 -0
  51. package/dist/src/integrations/application/delegation-outputs.js +1 -1
  52. package/dist/src/integrations/application/delivery-integration-verification.d.ts +13 -0
  53. package/dist/src/integrations/application/delivery-integration-verification.js +68 -0
  54. package/dist/src/integrations/delivery/application/delivery-projector.js +3 -0
  55. package/dist/src/integrations/delivery/application/merged-delivery-evidence.js +9 -1
  56. package/dist/src/integrations/delivery/contracts/views.d.ts +2 -0
  57. package/dist/src/integrations/fake/external-source.d.ts +5 -2
  58. package/dist/src/integrations/fake/external-source.js +12 -2
  59. package/dist/src/integrations/fake/inbound-translator.js +7 -2
  60. package/dist/src/integrations/fake/provider.d.ts +17 -0
  61. package/dist/src/integrations/fake/provider.js +18 -2
  62. package/dist/src/integrations/github/application/pull-request-translation.js +2 -0
  63. package/dist/src/integrations/github/contracts/events.d.ts +3 -1
  64. package/dist/src/integrations/github/contracts/events.js +3 -1
  65. package/dist/src/integrations/github/contracts/payloads.d.ts +23 -0
  66. package/dist/src/integrations/github/infrastructure/check-execution.d.ts +9 -0
  67. package/dist/src/integrations/github/infrastructure/check-execution.js +68 -0
  68. package/dist/src/integrations/github/infrastructure/checkout-revision.d.ts +2 -0
  69. package/dist/src/integrations/github/infrastructure/checkout-revision.js +23 -0
  70. package/dist/src/integrations/github/infrastructure/client.d.ts +2 -0
  71. package/dist/src/integrations/github/infrastructure/client.js +4 -0
  72. package/dist/src/integrations/github/infrastructure/pr-check-subject.d.ts +7 -0
  73. package/dist/src/integrations/github/infrastructure/pr-check-subject.js +77 -0
  74. package/dist/src/integrations/github/infrastructure/pr-evidence.d.ts +6 -3
  75. package/dist/src/integrations/github/infrastructure/pr-evidence.js +1 -1
  76. package/dist/src/integrations/github/infrastructure/pr-source.d.ts +3 -5
  77. package/dist/src/integrations/github/infrastructure/pr-source.js +11 -1
  78. package/dist/src/integrations/github/infrastructure/workflow-run-evidence.d.ts +5 -0
  79. package/dist/src/integrations/github/infrastructure/workflow-run-evidence.js +22 -0
  80. package/dist/src/integrations/index.d.ts +1 -0
  81. package/dist/src/integrations/index.js +1 -0
  82. package/dist/src/orchestration/application/delegation-commands.d.ts +3 -0
  83. package/dist/src/orchestration/application/delivery-coordinator.d.ts +70 -1
  84. package/dist/src/orchestration/application/delivery-coordinator.js +31 -5
  85. package/dist/src/orchestration/application/delivery-facts-reader.js +1 -0
  86. package/dist/src/orchestration/application/delivery-integration-reader.d.ts +9 -0
  87. package/dist/src/orchestration/application/delivery-integration-reader.js +23 -0
  88. package/dist/src/orchestration/application/delivery-integration-service.d.ts +50 -0
  89. package/dist/src/orchestration/application/delivery-integration-service.js +228 -0
  90. package/dist/src/orchestration/application/delivery-preparation.d.ts +1 -0
  91. package/dist/src/orchestration/application/delivery-preparation.js +7 -2
  92. package/dist/src/orchestration/application/orchestration-service.d.ts +74 -3
  93. package/dist/src/orchestration/application/orchestration-service.js +55 -2
  94. package/dist/src/orchestration/contracts/config.d.ts +6 -0
  95. package/dist/src/orchestration/contracts/config.js +6 -0
  96. package/dist/src/orchestration/contracts/delivery-ports.d.ts +44 -0
  97. package/dist/src/orchestration/contracts/delivery.d.ts +58 -0
  98. package/dist/src/orchestration/contracts/delivery.js +53 -1
  99. package/dist/src/orchestration/contracts/event-decoder.js +2 -1
  100. package/dist/src/orchestration/contracts/event-factory.js +2 -0
  101. package/dist/src/orchestration/contracts/events.d.ts +3 -1
  102. package/dist/src/orchestration/contracts/events.js +1 -0
  103. package/dist/src/orchestration/contracts/vocabulary.d.ts +44 -1
  104. package/dist/src/orchestration/contracts/vocabulary.js +40 -1
  105. package/dist/src/orchestration/domain/compile-diagnostics.d.ts +1 -1
  106. package/dist/src/orchestration/domain/compile-diagnostics.js +5 -0
  107. package/dist/src/orchestration/domain/delivery-candidate.js +13 -0
  108. package/dist/src/orchestration/domain/delivery-facts.d.ts +7 -1
  109. package/dist/src/orchestration/domain/delivery-facts.js +33 -1
  110. package/dist/src/orchestration/domain/delivery-integration-policy.d.ts +7 -0
  111. package/dist/src/orchestration/domain/delivery-integration-policy.js +15 -0
  112. package/dist/src/orchestration/domain/delivery-integration.d.ts +54 -0
  113. package/dist/src/orchestration/domain/delivery-integration.js +144 -0
  114. package/dist/src/orchestration/domain/delivery-qa.d.ts +2 -1
  115. package/dist/src/orchestration/domain/delivery-qa.js +24 -4
  116. package/dist/src/orchestration/domain/delivery-workflow-policy.d.ts +3 -1
  117. package/dist/src/orchestration/domain/delivery-workflow-policy.js +19 -0
  118. package/dist/src/orchestration/domain/workflow-instance-events.js +1 -0
  119. package/dist/src/orchestration/index.d.ts +3 -2
  120. package/dist/src/orchestration/index.js +1 -1
  121. package/dist/src/surfaces/api/contracts/transport-values.js +1 -0
  122. package/dist/src/surfaces/api/contracts/work.d.ts +26 -0
  123. package/dist/src/surfaces/api/presenters/execution.js +1 -0
  124. package/dist/src/surfaces/mcp/delegation.js +5 -1
  125. package/dist/src/surfaces/web-assets/assets/index-ih1h3dxC.js +1192 -0
  126. package/dist/src/surfaces/web-assets/index.html +1 -1
  127. package/package.json +1 -1
  128. package/dist/src/surfaces/web-assets/assets/index-BfhxlN_h.js +0 -1192
@@ -2,7 +2,7 @@ import { z } from 'zod';
2
2
  import { brandedStringSchema } from '../../kernel/index.js';
3
3
  import { workItemId } from '../../work/index.js';
4
4
  import { delegationResultSchema } from './delegation.js';
5
- import { CandidateSourceKind, QaVerdict } from './vocabulary.js';
5
+ import { CandidateSourceKind, MaintenanceKind, QaVerdict, } from './vocabulary.js';
6
6
  const revision = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i);
7
7
  export const deliveryOutputKeySchema = z
8
8
  .object({ childWorkItemId: brandedStringSchema(workItemId), outputName: z.string().min(1) })
@@ -92,6 +92,21 @@ export const deliveryCandidateSchema = z
92
92
  candidateId: z.string().min(1),
93
93
  selectionRevision: z.number().int().positive(),
94
94
  repositories: z.array(candidateRepositorySchema).min(1),
95
+ /**
96
+ * The exact change subjects this candidate was built from. Maintenance that replaces any of
97
+ * them makes the candidate, and QA of it, historical rather than current.
98
+ */
99
+ subjects: z
100
+ .array(z
101
+ .object({
102
+ childWorkItemId: brandedStringSchema(workItemId),
103
+ outputName: z.string().min(1),
104
+ revision,
105
+ pullRequestBase: z.string().min(1),
106
+ baseRevision: z.string().min(1).optional(),
107
+ })
108
+ .strict())
109
+ .optional(),
95
110
  /** Non-change outputs (plans, evidence) the candidate was selected with. */
96
111
  context: z.array(deliveryOutputKeySchema),
97
112
  criteria: z.array(z.string().min(1)),
@@ -124,6 +139,43 @@ export const deliveryQaSchema = deliveryQaCommandSchema
124
139
  activationId: z.string().min(1).optional(),
125
140
  })
126
141
  .strict();
142
+ const subjectState = z
143
+ .object({
144
+ revision,
145
+ pullRequestBase: z.string().min(1),
146
+ baseRevision: z.string().min(1).optional(),
147
+ })
148
+ .strict();
149
+ /** Agent input: what it did to one selected change, for Wake to verify against the provider. */
150
+ export const deliveryMaintenanceCommandSchema = z
151
+ .object({
152
+ maintenanceId: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
153
+ target: deliveryOutputKeySchema,
154
+ kind: z.enum(MaintenanceKind),
155
+ /** The head the agent started from; it must be the target's current subject. */
156
+ expectedRevision: revision,
157
+ /** The resulting head and pull request base the agent published. */
158
+ revision,
159
+ pullRequestBase: z.string().min(1),
160
+ })
161
+ .strict();
162
+ /**
163
+ * An immutable new subject for a selected change. The earlier subject, its reviews, checks and
164
+ * QA stay historical; the PR keeps its original owner and the producer is the maintaining Run.
165
+ */
166
+ export const deliveryMaintenanceSchema = z
167
+ .object({
168
+ maintenanceId: z.string().min(1),
169
+ target: deliveryOutputKeySchema,
170
+ kind: z.enum(MaintenanceKind),
171
+ resourceId: z.string().min(1),
172
+ repositoryResourceId: z.string().min(1),
173
+ previous: subjectState,
174
+ current: subjectState.extend({ baseRevision: z.string().min(1).optional() }).strict(),
175
+ recordedAt: z.string().datetime({ offset: true }).optional(),
176
+ producer: z.object({ runId: z.string().min(1), activationId: z.string().min(1) }).strict(),
177
+ })
178
+ .strict();
127
179
  export class DeliveryRejectionError extends Error {
128
180
  code;
129
181
  constructor(code, message) {
@@ -1,7 +1,7 @@
1
1
  /* eslint-disable max-lines */
2
2
  import { z } from 'zod';
3
3
  import { delegationAttentionRequestSchema, delegationAttentionResolvedSchema, delegationAttentionResponseSchema, delegationInputsSchema, delegationJoinSchema, delegationReservationSchema, delegationResultSchema, delegationWaitSchema, } from './delegation.js';
4
- import { deliveryCandidateSchema, deliveryQaSchema, deliverySelectionSchema } from './delivery.js';
4
+ import { deliveryCandidateSchema, deliveryMaintenanceSchema, deliveryQaSchema, deliverySelectionSchema, } from './delivery.js';
5
5
  import { eventDataSchema, eventEnvelopeSchema } from '@atolis-hq/eventing';
6
6
  import { activationId, ActivityEventType, activityName, ActivityOutcomeKind, PullRequestCheckState, PullRequestMergeability, PullRequestState, } from '../../activities/index.js';
7
7
  import { WorkspaceMode } from '../../execution/index.js';
@@ -232,6 +232,7 @@ const eventSchemas = {
232
232
  [OrchestrationEventType.DeliverySelectionRevised]: workflowEnvelope(OrchestrationEventType.DeliverySelectionRevised, deliverySelectionSchema),
233
233
  [OrchestrationEventType.DeliveryCandidateRecorded]: workflowEnvelope(OrchestrationEventType.DeliveryCandidateRecorded, deliveryCandidateSchema),
234
234
  [OrchestrationEventType.DeliveryQaRecorded]: workflowEnvelope(OrchestrationEventType.DeliveryQaRecorded, deliveryQaSchema),
235
+ [OrchestrationEventType.DeliveryMaintenanceRecorded]: workflowEnvelope(OrchestrationEventType.DeliveryMaintenanceRecorded, deliveryMaintenanceSchema),
235
236
  [OrchestrationEventType.DelegationReserved]: workflowEnvelope(OrchestrationEventType.DelegationReserved, delegationReservationSchema),
236
237
  [OrchestrationEventType.DelegationRegistered]: workflowEnvelope(OrchestrationEventType.DelegationRegistered, z.object({ cohortId: z.string().min(1) }).strict()),
237
238
  [OrchestrationEventType.DelegationResultSelected]: workflowEnvelope(OrchestrationEventType.DelegationResultSelected, delegationResultSchema),
@@ -24,6 +24,8 @@ export function createOrchestrationEventData(input) {
24
24
  return createEventData(input);
25
25
  case OrchestrationEventType.DeliveryQaRecorded:
26
26
  return createEventData(input);
27
+ case OrchestrationEventType.DeliveryMaintenanceRecorded:
28
+ return createEventData(input);
27
29
  case OrchestrationEventType.DelegationReserved:
28
30
  return createEventData(input);
29
31
  case OrchestrationEventType.DelegationRegistered:
@@ -4,7 +4,7 @@ import type { WorkItemId } from '../../work/index.js';
4
4
  import type { OrchestrationWaitingActivityOutcome } from './activity-outcome.js';
5
5
  import type { ApprovalAuthority, CompiledResourceTransition, CompiledWorkflow, StageConfig, TransitionTarget } from './config.js';
6
6
  import type { DelegationAttentionRequest, DelegationAttentionResponse, DelegationInputs, DelegationReservation, DelegationResult } from './delegation.js';
7
- import type { DeliveryCandidate, DeliveryCompletionBlock, DeliveryQa, DeliverySelection } from './delivery.js';
7
+ import type { DeliveryCandidate, DeliveryCompletionBlock, DeliveryMaintenance, DeliveryQa, DeliverySelection } from './delivery.js';
8
8
  import type { CommandName, OrchestrationGroupId, SignalName, StageName, WorkflowInstanceId, WorkflowName } from './identifiers.js';
9
9
  import type { ChildOrchestrationGroupStreamId, ChildOrchestrationGroupStreamRef, PrimaryOrchestrationGroupStreamRef, WorkflowDefinitionsStreamRef, WorkflowInstanceStreamRef } from './streams.js';
10
10
  export declare const OrchestrationEventType: {
@@ -24,6 +24,7 @@ export declare const OrchestrationEventType: {
24
24
  readonly DeliverySelectionRevised: "orchestration.delivery-selection-revised";
25
25
  readonly DeliveryCandidateRecorded: "orchestration.delivery-candidate-recorded";
26
26
  readonly DeliveryQaRecorded: "orchestration.delivery-qa-recorded";
27
+ readonly DeliveryMaintenanceRecorded: "orchestration.delivery-maintenance-recorded";
27
28
  readonly WorkflowDefinitionRegistered: "orchestration.workflow-definition-registered";
28
29
  readonly InstanceStarted: "orchestration.instance-started";
29
30
  readonly StageEntered: "orchestration.stage-entered";
@@ -95,6 +96,7 @@ export interface OrchestrationEventPayloads {
95
96
  readonly [OrchestrationEventType.DeliverySelectionRevised]: DeliverySelection;
96
97
  readonly [OrchestrationEventType.DeliveryCandidateRecorded]: DeliveryCandidate;
97
98
  readonly [OrchestrationEventType.DeliveryQaRecorded]: DeliveryQa;
99
+ readonly [OrchestrationEventType.DeliveryMaintenanceRecorded]: DeliveryMaintenance;
98
100
  readonly [OrchestrationEventType.DelegationReserved]: DelegationReservation;
99
101
  readonly [OrchestrationEventType.DelegationRegistered]: {
100
102
  readonly cohortId: string;
@@ -16,6 +16,7 @@ export const OrchestrationEventType = {
16
16
  DeliverySelectionRevised: 'orchestration.delivery-selection-revised',
17
17
  DeliveryCandidateRecorded: 'orchestration.delivery-candidate-recorded',
18
18
  DeliveryQaRecorded: 'orchestration.delivery-qa-recorded',
19
+ DeliveryMaintenanceRecorded: 'orchestration.delivery-maintenance-recorded',
19
20
  WorkflowDefinitionRegistered: 'orchestration.workflow-definition-registered',
20
21
  InstanceStarted: 'orchestration.instance-started',
21
22
  StageEntered: 'orchestration.stage-entered',
@@ -119,6 +119,12 @@ export declare const DeliveryRejection: {
119
119
  readonly InvalidVerdict: "invalid-verdict";
120
120
  /** An identity was reused for different content. */
121
121
  readonly Conflict: "identity-conflict";
122
+ /** Maintenance named a target that is not a selected, unmerged change. */
123
+ readonly NotMaintainable: "not-maintainable";
124
+ /** Maintenance did not start from the target's current subject, or the provider disagrees. */
125
+ readonly MaintenanceMismatch: "maintenance-mismatch";
126
+ /** An earlier writer of the target is unresolved; reconcile it before another writes. */
127
+ readonly AmbiguousWriter: "ambiguous-writer";
122
128
  };
123
129
  export type DeliveryRejection = ValueOf<typeof DeliveryRejection>;
124
130
  export declare const QaVerdict: {
@@ -138,7 +144,44 @@ export type CandidateSourceKind = ValueOf<typeof CandidateSourceKind>;
138
144
  export declare const DeliveryCompletion: {
139
145
  /** The parent may finish once the current candidate has an effective QA pass. */
140
146
  readonly QaApproved: "qa-approved";
141
- /** The parent additionally needs governed integration, which is not yet available. */
147
+ /** The parent additionally needs every selected change merged through governed integration. */
142
148
  readonly MergeRequired: "merge-required";
143
149
  };
144
150
  export type DeliveryCompletion = ValueOf<typeof DeliveryCompletion>;
151
+ /** What an agent did to a selected change so it can integrate; each records a new subject. */
152
+ export declare const MaintenanceKind: {
153
+ readonly Retarget: "retarget";
154
+ readonly Rebase: "rebase";
155
+ readonly Resolve: "resolve-conflicts";
156
+ };
157
+ export type MaintenanceKind = ValueOf<typeof MaintenanceKind>;
158
+ /** Where a selected change stands in governed integration, derived from actual provider state. */
159
+ export declare const IntegrationState: {
160
+ readonly Merged: "integrated";
161
+ readonly Ready: "ready-to-integrate";
162
+ readonly AwaitingLowerLayer: "awaiting-lower-layer";
163
+ readonly MaintenanceRequired: "maintenance-required";
164
+ readonly Closed: "closed-unmerged";
165
+ readonly Held: "held";
166
+ readonly Unobserved: "unobserved";
167
+ };
168
+ export type IntegrationState = ValueOf<typeof IntegrationState>;
169
+ export declare const MaintenanceReason: {
170
+ /** A lower layer merged, so the change still targets a branch that no longer carries the stack. */
171
+ readonly Retarget: "retarget";
172
+ readonly Conflict: "merge-conflict";
173
+ /** The provider head is not the recorded subject: another writer changed the branch. */
174
+ readonly HeadMoved: "head-moved";
175
+ /** The base moved for a reason outside the delivery, so the tested combination is unproven. */
176
+ readonly BaseMoved: "base-moved";
177
+ };
178
+ export type MaintenanceReason = ValueOf<typeof MaintenanceReason>;
179
+ /** How the integration base changed since the subject was recorded. */
180
+ export declare const BaseMovement: {
181
+ readonly None: "none";
182
+ /** A selected change merged; the QA candidate already contained it. */
183
+ readonly PlannedProgress: "planned-progress";
184
+ /** Nothing in the delivery explains it; it is never credited as progress. */
185
+ readonly Unrelated: "unrelated";
186
+ };
187
+ export type BaseMovement = ValueOf<typeof BaseMovement>;
@@ -108,6 +108,12 @@ export const DeliveryRejection = defineClosedVocabulary({
108
108
  InvalidVerdict: 'invalid-verdict',
109
109
  /** An identity was reused for different content. */
110
110
  Conflict: 'identity-conflict',
111
+ /** Maintenance named a target that is not a selected, unmerged change. */
112
+ NotMaintainable: 'not-maintainable',
113
+ /** Maintenance did not start from the target's current subject, or the provider disagrees. */
114
+ MaintenanceMismatch: 'maintenance-mismatch',
115
+ /** An earlier writer of the target is unresolved; reconcile it before another writes. */
116
+ AmbiguousWriter: 'ambiguous-writer',
111
117
  });
112
118
  export const QaVerdict = defineClosedVocabulary({
113
119
  Pass: 'pass',
@@ -124,6 +130,39 @@ export const CandidateSourceKind = defineClosedVocabulary({
124
130
  export const DeliveryCompletion = defineClosedVocabulary({
125
131
  /** The parent may finish once the current candidate has an effective QA pass. */
126
132
  QaApproved: 'qa-approved',
127
- /** The parent additionally needs governed integration, which is not yet available. */
133
+ /** The parent additionally needs every selected change merged through governed integration. */
128
134
  MergeRequired: 'merge-required',
129
135
  });
136
+ /** What an agent did to a selected change so it can integrate; each records a new subject. */
137
+ export const MaintenanceKind = defineClosedVocabulary({
138
+ Retarget: 'retarget',
139
+ Rebase: 'rebase',
140
+ Resolve: 'resolve-conflicts',
141
+ });
142
+ /** Where a selected change stands in governed integration, derived from actual provider state. */
143
+ export const IntegrationState = defineClosedVocabulary({
144
+ Merged: 'integrated',
145
+ Ready: 'ready-to-integrate',
146
+ AwaitingLowerLayer: 'awaiting-lower-layer',
147
+ MaintenanceRequired: 'maintenance-required',
148
+ Closed: 'closed-unmerged',
149
+ Held: 'held',
150
+ Unobserved: 'unobserved',
151
+ });
152
+ export const MaintenanceReason = defineClosedVocabulary({
153
+ /** A lower layer merged, so the change still targets a branch that no longer carries the stack. */
154
+ Retarget: 'retarget',
155
+ Conflict: 'merge-conflict',
156
+ /** The provider head is not the recorded subject: another writer changed the branch. */
157
+ HeadMoved: 'head-moved',
158
+ /** The base moved for a reason outside the delivery, so the tested combination is unproven. */
159
+ BaseMoved: 'base-moved',
160
+ });
161
+ /** How the integration base changed since the subject was recorded. */
162
+ export const BaseMovement = defineClosedVocabulary({
163
+ None: 'none',
164
+ /** A selected change merged; the QA candidate already contained it. */
165
+ PlannedProgress: 'planned-progress',
166
+ /** Nothing in the delivery explains it; it is never credited as progress. */
167
+ Unrelated: 'unrelated',
168
+ });
@@ -1,4 +1,4 @@
1
- import type { ActivityRegistry } from '../../activities/index.js';
1
+ import { type ActivityRegistry } from '../../activities/index.js';
2
2
  import type { CompiledStage } from '../contracts/config.js';
3
3
  import type { StageName } from '../contracts/identifiers.js';
4
4
  export interface WorkflowCompileDiagnostic {
@@ -1,8 +1,13 @@
1
+ import { ActivityOutcomeKind } from '../../activities/index.js';
2
+ const hasDeliveryScope = (stage) => typeof stage.with === 'object' && stage.with !== null && 'scope' in stage.with;
1
3
  export function reportUnroutedOutcomes(workflow, stages, activities, report) {
2
4
  for (const [stage, configured] of Object.entries(stages)) {
3
5
  for (const outcome of activities.describe(configured.activity).outcomeKinds) {
4
6
  if (Object.hasOwn(configured.on, outcome))
5
7
  continue;
8
+ // Only a parent delivery scope can finish with nothing left to integrate.
9
+ if (outcome === ActivityOutcomeKind.Integrated && !hasDeliveryScope(configured))
10
+ continue;
6
11
  report({
7
12
  workflow,
8
13
  stage,
@@ -33,6 +33,19 @@ export function planCandidate(facts, command, root) {
33
33
  candidateId: command.candidateId,
34
34
  selectionRevision: current.revision,
35
35
  repositories: repositories.sort((a, b) => a.resourceId.localeCompare(b.resourceId)),
36
+ subjects: current.entries.flatMap((entry) => isChange(entry.output)
37
+ ? [
38
+ {
39
+ childWorkItemId: entry.childWorkItemId,
40
+ outputName: entry.output.name,
41
+ revision: entry.output.reference.revision,
42
+ pullRequestBase: entry.output.reference.pullRequestBase,
43
+ ...(entry.output.reference.baseRevision === undefined
44
+ ? {}
45
+ : { baseRevision: entry.output.reference.baseRevision }),
46
+ },
47
+ ]
48
+ : []),
36
49
  context: current.entries
37
50
  .filter((entry) => !isChange(entry.output))
38
51
  .map((entry) => ({
@@ -1,5 +1,5 @@
1
1
  import type { DelegationReservation, DelegationResult } from '../contracts/delegation.js';
2
- import { DeliveryRejectionError, type DeliveryCandidate, type DeliveryOutputKey, type DeliveryQa, type DeliverySelection } from '../contracts/delivery.js';
2
+ import { DeliveryRejectionError, type DeliveryCandidate, type DeliveryMaintenance, type DeliveryOutputKey, type DeliveryQa, type DeliverySelection } from '../contracts/delivery.js';
3
3
  import type { DeliveryRejection } from '../contracts/vocabulary.js';
4
4
  export type Output = DelegationResult['outputs'][number];
5
5
  export type Child = DelegationReservation['children'][number];
@@ -15,6 +15,8 @@ export interface DeliveryFacts {
15
15
  readonly selections: readonly DeliverySelection[];
16
16
  readonly candidates: readonly DeliveryCandidate[];
17
17
  readonly qa: readonly DeliveryQa[];
18
+ /** Agent maintenance of selected changes, oldest first; each is a new immutable subject. */
19
+ readonly maintenance: readonly DeliveryMaintenance[];
18
20
  }
19
21
  export declare const outputKey: (key: DeliveryOutputKey) => string;
20
22
  export declare const entryKey: (entry: {
@@ -25,6 +27,10 @@ export declare const reject: (code: DeliveryRejection, message: string) => Deliv
25
27
  export declare const isChange: (output: Output) => output is Output & {
26
28
  reference: ChangeReference;
27
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
+ */
28
34
  export declare function currentSelection(facts: DeliveryFacts): DeliverySelection | undefined;
29
35
  export interface Requirement {
30
36
  readonly cohortId: string;
@@ -3,8 +3,40 @@ export const outputKey = (key) => `${key.childWorkItemId}/${key.outputName}`;
3
3
  export const entryKey = (entry, name) => `${entry.cohortId}/${entry.assignmentId}/${name}`;
4
4
  export const reject = (code, message) => new DeliveryRejectionError(code, message);
5
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
+ */
6
10
  export function currentSelection(facts) {
7
- return facts.selections.at(-1);
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
+ };
8
40
  }
9
41
  /** Original required assignments: those not themselves declared as a replacement. */
10
42
  export function requirements(reservations) {
@@ -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
+ }
@@ -1,6 +1,7 @@
1
1
  import type { DeliveryCandidate, DeliveryQa, DeliveryQaCommand } from '../contracts/delivery.js';
2
2
  import { DeliveryCompletion } from '../contracts/vocabulary.js';
3
3
  import { type DeliveryFacts } from './delivery-facts.js';
4
+ import type { IntegrationOutcome } from './delivery-integration.js';
4
5
  /** The exact repository and revision set QA must have checked. */
5
6
  export declare const revisionSet: (items: readonly {
6
7
  resourceId: string;
@@ -29,4 +30,4 @@ export interface CompletionDecision {
29
30
  readonly reason?: string;
30
31
  }
31
32
  /** DC-24 handoff boundary: QA approval finishes a QA-approved parent but never a merge-required one. */
32
- export declare function completionDecision(state: DeliveryState, mode: DeliveryCompletion): CompletionDecision;
33
+ export declare function completionDecision(state: DeliveryState, mode: DeliveryCompletion, integration?: IntegrationOutcome): CompletionDecision;