@adea-ai/app-framework 0.39.2 → 0.39.4

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 (199) hide show
  1. package/README.md +158 -52
  2. package/dist/app/application.d.ts +0 -1
  3. package/dist/app/application.js +8 -6
  4. package/dist/app/create-application.js +3 -11
  5. package/dist/app/service-registry.d.ts +0 -1
  6. package/dist/app/service-registry.js +3 -3
  7. package/dist/app/value-guards.d.ts +2 -0
  8. package/dist/app/value-guards.js +6 -1
  9. package/dist/appearance/appearance-host.d.ts +1 -1
  10. package/dist/appearance/appearance-host.js +11 -2
  11. package/dist/appearance/appearance-preferences.d.ts +0 -1
  12. package/dist/appearance/custom-theme-import.d.ts +8 -2
  13. package/dist/appearance/custom-theme-import.js +58 -23
  14. package/dist/appearance/custom-theme-library.d.ts +3 -3
  15. package/dist/appearance/custom-theme-library.js +3 -3
  16. package/dist/appearance/theme-file-importer.d.ts +1 -1
  17. package/dist/appearance/theme-file-importer.js +2 -1
  18. package/dist/appearance/theme-library-mutation.d.ts +7 -0
  19. package/dist/appearance/theme-library-mutation.js +10 -2
  20. package/dist/appearance/theme-library-store.d.ts +17 -13
  21. package/dist/appearance/theme-library-store.js +35 -22
  22. package/dist/appearance/theme-record-adapter.js +1 -2
  23. package/dist/appearance/theme-registry.js +0 -1
  24. package/dist/cli/cli-runner.d.ts +3 -2
  25. package/dist/cli/cli-runner.js +5 -10
  26. package/dist/cli/release-assets-plan-cli.js +2 -2
  27. package/dist/cli/release-cut-cli.js +2 -3
  28. package/dist/cli/release-descriptor-staging-cli.js +2 -2
  29. package/dist/cli/release-finalize-cli.js +3 -3
  30. package/dist/cli/release-promote-cli.js +2 -2
  31. package/dist/cli/release-publish-cli.js +2 -2
  32. package/dist/cli/release-sign-cli.js +2 -1
  33. package/dist/cli/release-step-cli.js +2 -2
  34. package/dist/desktop/channel-proof.js +27 -11
  35. package/dist/desktop/client-assets.d.ts +6 -1
  36. package/dist/desktop/client-assets.js +16 -3
  37. package/dist/desktop/client-dev-proxy.d.ts +0 -2
  38. package/dist/desktop/client-dev-proxy.js +2 -2
  39. package/dist/desktop/desktop-client.js +2 -1
  40. package/dist/desktop/desktop-gateway.js +24 -82
  41. package/dist/desktop/desktop-host-websocket.d.ts +5 -1
  42. package/dist/desktop/desktop-host-websocket.js +9 -7
  43. package/dist/desktop/desktop-host.d.ts +5 -0
  44. package/dist/desktop/desktop-host.js +3 -0
  45. package/dist/desktop/desktop-stream.js +5 -10
  46. package/dist/desktop/typed-array-intrinsics.d.ts +6 -0
  47. package/dist/desktop/typed-array-intrinsics.js +13 -1
  48. package/dist/developer-app/developer-app.d.ts +1 -1
  49. package/dist/developer-app/developer-app.js +26 -13
  50. package/dist/framework-source.json +1 -1
  51. package/dist/installer/command-artifact.d.ts +1 -0
  52. package/dist/installer/command-artifact.js +47 -27
  53. package/dist/installer/installed-payload.js +3 -1
  54. package/dist/installer/installer-ci-bootstrap.js +5 -6
  55. package/dist/installer/installer-ci-preflight.js +3 -3
  56. package/dist/installer/installer-identity.d.ts +0 -22
  57. package/dist/installer/installer-identity.js +3 -53
  58. package/dist/installer/installer-image-mount.d.ts +0 -1
  59. package/dist/installer/installer-image-mount.js +1 -1
  60. package/dist/installer/installer-observation.d.ts +5 -5
  61. package/dist/installer/installer-observation.js +32 -47
  62. package/dist/installer/installer-process-cleanup.js +2 -2
  63. package/dist/installer/installer-renderer-evidence.js +7 -28
  64. package/dist/installer/installer-upgrade-command.js +8 -20
  65. package/dist/installer/installer-worker-guard.js +3 -3
  66. package/dist/native/cef-helper.js +4 -4
  67. package/dist/native/desktop-build.d.ts +0 -3
  68. package/dist/native/desktop-build.js +2 -2
  69. package/dist/native/electrobun-source-patch.d.ts +4 -0
  70. package/dist/native/electrobun-source-patch.js +5 -1
  71. package/dist/native/native-utilities.js +4 -3
  72. package/dist/native/pinned-download.d.ts +16 -0
  73. package/dist/native/pinned-download.js +42 -0
  74. package/dist/native/posix-launcher-build.js +15 -35
  75. package/dist/native/posix-tree-removal.js +21 -33
  76. package/dist/native/sidecar-services.d.ts +0 -2
  77. package/dist/native/sidecar-services.js +1 -1
  78. package/dist/native/sidecar.d.ts +3 -0
  79. package/dist/native/sidecar.js +15 -2
  80. package/dist/native/window-surface-store.js +3 -3
  81. package/dist/native/windows-extractor-build.d.ts +6 -16
  82. package/dist/native/windows-extractor-build.js +11 -14
  83. package/dist/release/feed-release-cut.d.ts +2 -6
  84. package/dist/release/feed-release-cut.js +5 -93
  85. package/dist/release/feed-state.js +1 -5
  86. package/dist/release/github-release-cut.js +5 -66
  87. package/dist/release/github-release-provenance.d.ts +2 -0
  88. package/dist/release/github-release-provenance.js +4 -7
  89. package/dist/release/github-release-publisher.js +2 -2
  90. package/dist/release/github-release-qualification.js +3 -3
  91. package/dist/release/local-release.d.ts +3 -3
  92. package/dist/release/local-release.js +12 -23
  93. package/dist/release/qualification-run.js +1 -1
  94. package/dist/release/release-assets-plan.js +1 -1
  95. package/dist/release/release-config.d.ts +7 -15
  96. package/dist/release/release-config.js +25 -29
  97. package/dist/release/release-cut-command.d.ts +1 -1
  98. package/dist/release/release-cut-command.js +1 -1
  99. package/dist/release/release-cut.d.ts +5 -32
  100. package/dist/release/release-cut.js +9 -55
  101. package/dist/release/release-descriptor-staging.js +3 -8
  102. package/dist/release/release-promotion.js +2 -1
  103. package/dist/release/release-publish-command.js +5 -15
  104. package/dist/release/release-qualification.js +1 -1
  105. package/dist/shared/bounded-body.d.ts +33 -0
  106. package/dist/shared/bounded-body.js +102 -0
  107. package/dist/shared/file-system.d.ts +12 -0
  108. package/dist/shared/file-system.js +40 -0
  109. package/dist/shell/app-shell.js +29 -14
  110. package/dist/shell/app-utilities.d.ts +2 -1
  111. package/dist/shell/app-utilities.js +2 -1
  112. package/dist/shell/application-menu.d.ts +1 -1
  113. package/dist/shell/application-menu.js +7 -3
  114. package/dist/shell/poll.d.ts +27 -0
  115. package/dist/shell/poll.js +88 -0
  116. package/dist/update-helper.bundle.js +268 -144
  117. package/dist/updates/channel-update-manager.js +0 -1
  118. package/dist/updates/desktop-updater.d.ts +9 -0
  119. package/dist/updates/desktop-updater.js +103 -50
  120. package/dist/updates/feed/release-feed.d.ts +7 -4
  121. package/dist/updates/feed/release-feed.js +3 -7
  122. package/dist/updates/feed/release-location.js +6 -26
  123. package/dist/updates/feed/release-version.d.ts +7 -2
  124. package/dist/updates/feed/release-version.js +9 -2
  125. package/dist/updates/feed/signed-release.d.ts +1 -1
  126. package/dist/updates/feed/signed-release.js +2 -2
  127. package/dist/updates/feed/update-discovery.js +2 -6
  128. package/dist/updates/helper/launch-gate-recovery.js +28 -78
  129. package/dist/updates/helper/resume-staging.d.ts +14 -3
  130. package/dist/updates/helper/resume-staging.js +23 -37
  131. package/dist/updates/helper/update-helper.d.ts +6 -2
  132. package/dist/updates/helper/update-helper.js +38 -33
  133. package/dist/updates/helper/update-resume.js +9 -6
  134. package/dist/updates/install/update-extraction.js +28 -8
  135. package/dist/updates/install/update-handoff-plan.d.ts +0 -1
  136. package/dist/updates/install/update-handoff-plan.js +3 -4
  137. package/dist/updates/install/update-swap-stage.js +1 -6
  138. package/dist/updates/install/update-swap.d.ts +5 -2
  139. package/dist/updates/install/update-swap.js +193 -72
  140. package/dist/updates/launch/helper-exit-wait.d.ts +6 -0
  141. package/dist/updates/launch/helper-exit-wait.js +18 -0
  142. package/dist/updates/launch/packaged-update-startup.js +8 -6
  143. package/dist/updates/launch/update-launch-gate.js +7 -14
  144. package/dist/updates/locks/stable-file.js +4 -1
  145. package/dist/updates/locks/update-helper-presence.d.ts +12 -0
  146. package/dist/updates/locks/update-helper-presence.js +27 -0
  147. package/dist/updates/retention/retention-cleanup.js +10 -9
  148. package/dist/updates/retention/retention-maintenance.d.ts +40 -0
  149. package/dist/updates/retention/retention-maintenance.js +95 -0
  150. package/dist/updates/retention/retention-prune-progress.js +4 -5
  151. package/dist/updates/retention/retirement-inventory.d.ts +13 -0
  152. package/dist/updates/retention/retirement-inventory.js +39 -31
  153. package/dist/updates/retention/retirement-records.d.ts +1 -4
  154. package/dist/updates/retention/retirement-records.js +18 -32
  155. package/dist/updates/retention/update-retention-marker.d.ts +4 -0
  156. package/dist/updates/retention/update-retention-marker.js +9 -14
  157. package/dist/updates/retention/update-retirement.d.ts +12 -0
  158. package/dist/updates/retention/update-retirement.js +59 -31
  159. package/dist/updates/update-adapter.d.ts +1 -23
  160. package/dist/updates/update-adapter.js +31 -24
  161. package/dist/updates/update-channel-store.d.ts +2 -1
  162. package/dist/updates/update-channel-store.js +6 -4
  163. package/dist/updates/update-manager.js +2 -2
  164. package/dist/updates/update-services.d.ts +1 -1
  165. package/dist/updates/update-services.js +9 -4
  166. package/dist/updates/update-state-store.d.ts +0 -2
  167. package/dist/updates/update-state-store.js +5 -12
  168. package/dist/updates/update-state.d.ts +6 -10
  169. package/dist/updates/update-state.js +1 -1
  170. package/dist/views/app-help.d.ts +1 -1
  171. package/dist/views/app-help.js +1 -3
  172. package/dist/views/appearance-surface.js +15 -8
  173. package/dist/views/update-surface.d.ts +1 -3
  174. package/dist/views/update-surface.js +2 -2
  175. package/package.json +18 -16
  176. package/src/app/application.tsx +13 -6
  177. package/src/appearance/appearance-host.tsx +17 -7
  178. package/src/appearance/appearance-preferences.ts +0 -1
  179. package/src/appearance/custom-theme-import.ts +99 -26
  180. package/src/appearance/custom-theme-library.ts +3 -2
  181. package/src/appearance/theme-file-importer.ts +3 -2
  182. package/src/appearance/theme-library-mutation.ts +20 -8
  183. package/src/appearance/theme-library-schema.ts +7 -0
  184. package/src/appearance/theme-library-store.ts +41 -26
  185. package/src/desktop/client-assets.ts +27 -12
  186. package/src/shell/app-shell.tsx +33 -13
  187. package/src/shell/app-utilities.tsx +7 -1
  188. package/src/shell/poll.ts +125 -0
  189. package/src/updates/feed/release-version.ts +11 -3
  190. package/src/updates/update-adapter.ts +27 -44
  191. package/src/updates/update-state.ts +7 -13
  192. package/src/views/app-help.tsx +1 -1
  193. package/src/views/appearance-surface.tsx +39 -11
  194. package/src/views/update-surface.tsx +0 -4
  195. package/templates/application/.github/workflows/release-assets.yml +2 -2
  196. package/templates/application/README.md +3 -3
  197. package/dist/native/cef-helper-download.d.ts +0 -1
  198. package/dist/native/cef-helper-download.js +0 -35
  199. package/src/desktop/client-response-lifecycle.ts +0 -305
@@ -67,6 +67,8 @@ export type UpdaterOptions = {
67
67
  export declare function createUpdater(options: UpdaterOptions): {
68
68
  status(): Promise<DesktopUpdateStatus>;
69
69
  check: () => Promise<DesktopUpdateStatus>;
70
+ /** The changelog the status digest names. */
71
+ changelog(): Promise<string>;
70
72
  channel(): Promise<UpdateChannel>;
71
73
  saveChannel(channel: UpdateChannel): Promise<UpdateChannel>;
72
74
  install(request: UpdateInstallRequest): Promise<DesktopUpdateStatus>;
@@ -103,6 +105,13 @@ export declare function createDesktopUpdater(options: {
103
105
  abortPreparedQuit?(): void | Promise<void>;
104
106
  quit(timing?: UpdateShutdownTiming): void | Promise<void>;
105
107
  log(line: string): void;
108
+ /**
109
+ * How long this launch must stay up before the framework acknowledges the installed
110
+ * update as healthy and prunes retired app copies older than the rollback tree (the
111
+ * installed tree and the one it replaced are kept). Default one minute; `false` leaves
112
+ * acknowledgement to the app's own `acknowledgeHealthy` call, which also prunes.
113
+ */
114
+ healthyAfterMs?: number | false;
106
115
  }): Promise<DesktopUpdater>;
107
116
  export { updatePlatform, installTarget } from './install-target';
108
117
  export { acquireRetainedDesktopClientAssets, resumeAndAcquireRetainedDesktopClientAssets, } from './retained-client-assets';
@@ -4,19 +4,23 @@ import { feedUrl, parseReleaseFeed } from "./feed/release-feed.js";
4
4
  import { createUpdateChannelStore, releaseChannelForUpdate } from "./update-channel-store.js";
5
5
  import { armUpdateHelper } from "./install/update-arm.js";
6
6
  import { resumeUpdate } from "./helper/update-resume.js";
7
- import { acknowledgeRetiredUpdateHealthy } from "./retention/update-retirement.js";
7
+ import { acknowledgeRetiredUpdateHealthy, acknowledgeRetiredUpdateLineage } from "./retention/update-retirement.js";
8
+ import { pruneRetiredUpdates } from "./retention/retention-maintenance.js";
8
9
  import { findPendingUpdateHealthAcknowledgement } from "./retention/retirement-inventory.js";
9
10
  import { scheduleUpdateShutdown } from "./helper/update-shutdown.js";
10
11
  import { UpdateCleanupPendingError, findUpdateCleanupTerminalError } from "./update-cleanup-error.js";
11
12
  import { stageUpdateSwap } from "./install/update-swap-stage.js";
12
13
  import { completeOwnedUpdateDownload, createOwnedUpdateDownload, initializeOwnedUpdateDownloadRoot } from "./install/update-download-cleanup.js";
13
14
  import { downloadVerifiedRelease } from "./install/update-download.js";
15
+ import { readUpdateStageState } from "./update-state-store.js";
16
+ import { updateStagingFor } from "./install/update-swap.js";
14
17
  import { UpdatePreflightError } from "./update-preflight-error.js";
15
18
  import { installTarget, updatePlatform } from "./install-target.js";
16
19
  import { acquireRetainedDesktopClientAssets, canonicalTargetForRecovery, resumeAndAcquireRetainedDesktopClientAssets } from "./retained-client-assets.js";
17
20
  import { parseUpdateChannel, parseUpdateInstall, registerUpdateServices } from "./update-services.js";
18
21
  import { mkdir, realpath } from "node:fs/promises";
19
22
  import { join } from "node:path";
23
+ import { createHash } from "node:crypto";
20
24
  // src/updates/desktop-updater.ts
21
25
  /**
22
26
  * The desktop host's signed updater, the same for every framework app: the
@@ -40,8 +44,7 @@ var HEALTH_ACK_HELPER_WAIT_MS = 5e3;
40
44
  function discoveryNames(platform) {
41
45
  return {
42
46
  stable: `stable-${platform}.json`,
43
- "pre-release": `daily-${platform}.json`,
44
- dev: `dev-${platform}.json`
47
+ "pre-release": `daily-${platform}.json`
45
48
  };
46
49
  }
47
50
  /**
@@ -125,6 +128,8 @@ function createUpdater(options) {
125
128
  }).catch(() => {});
126
129
  return operation;
127
130
  };
131
+ const changelog = options.changelog ?? "";
132
+ const changelogDigest = changelog ? createHash("sha256").update(changelog).digest("hex").slice(0, 16) : void 0;
128
133
  let inFlight = null;
129
134
  const snapshot = () => {
130
135
  const state = manager?.status();
@@ -136,7 +141,8 @@ function createUpdater(options) {
136
141
  available_version: available,
137
142
  release_date: null,
138
143
  release_notes: null,
139
- changelog: options.changelog ?? "",
144
+ changelog: "",
145
+ ...changelogDigest ? { changelog_digest: changelogDigest } : {},
140
146
  github_url: lastTag ? `${releases}/tag/${lastTag}` : releases,
141
147
  phase,
142
148
  downloaded_bytes: 0,
@@ -163,6 +169,10 @@ function createUpdater(options) {
163
169
  return inFlight ?? snapshot();
164
170
  },
165
171
  check,
172
+ /** The changelog the status digest names. */
173
+ async changelog() {
174
+ return changelog;
175
+ },
166
176
  async channel() {
167
177
  return manager ? manager.readChannel() : "stable";
168
178
  },
@@ -209,6 +219,14 @@ function createUpdater(options) {
209
219
  }
210
220
  };
211
221
  }
222
+ /** Create a private app directory if missing and resolve it. */
223
+ async function privateDirectory(path) {
224
+ await mkdir(path, {
225
+ recursive: true,
226
+ mode: 448
227
+ });
228
+ return realpath(path);
229
+ }
212
230
  /**
213
231
  * The updater for the packaged app at `entryDirectory`. Clears downloads left
214
232
  * by an earlier run and reports what an earlier helper did.
@@ -246,12 +264,8 @@ async function createDesktopUpdater(options) {
246
264
  restart: async () => {}
247
265
  });
248
266
  const target = await canonicalTargetForRecovery(installTarget(options.entryDirectory, platform));
249
- const stateDirectory = options.stateDirectory ?? options.dataDirectory;
250
- await mkdir(stateDirectory, {
251
- recursive: true,
252
- mode: 448
253
- });
254
- const channelStore = createUpdateChannelStore(await realpath(stateDirectory));
267
+ const dataDirectory = await privateDirectory(options.dataDirectory);
268
+ const channelStore = createUpdateChannelStore(options.stateDirectory === void 0 ? dataDirectory : await privateDirectory(options.stateDirectory));
255
269
  const storedChannel = options.startup ? options.startup.savedChannel : await channelStore.read().catch((error) => {
256
270
  options.log(`update channel read failed: ${String(error)}`);
257
271
  return null;
@@ -272,11 +286,6 @@ async function createDesktopUpdater(options) {
272
286
  if (resumed?.status === "staged") options.log(`a staged ${release.appName} update ${resumed.version} is waiting to be installed`);
273
287
  if (resumed?.status === "recovery-required") options.log("an older update staging directory needs manual recovery; it was preserved");
274
288
  let recoveryPending = resumed === null || resumed.status === "in-progress" || resumed.status === "recovery-required";
275
- await mkdir(options.dataDirectory, {
276
- recursive: true,
277
- mode: 448
278
- });
279
- const dataDirectory = await realpath(options.dataDirectory);
280
289
  const downloadsRoot = await initializeOwnedUpdateDownloadRoot(join(dataDirectory, "updates-v2"));
281
290
  const downloadLeases = /* @__PURE__ */ new Map();
282
291
  const manager = createChannelUpdateManager({
@@ -377,47 +386,91 @@ async function createDesktopUpdater(options) {
377
386
  }
378
387
  }
379
388
  });
380
- return createUpdater({
381
- ...updater,
382
- manager,
383
- async pendingHealthAcknowledgement() {
384
- let channel = selectedChannel;
385
- try {
386
- channel = releaseChannelForUpdate(await channelStore.read());
387
- } catch (error) {
388
- options.log(`update channel read failed during health recovery: ${String(error)}`);
389
- }
390
- if (channel) {
391
- const deadline = performance.now() + HEALTH_ACK_HELPER_WAIT_MS;
392
- for (;;) {
393
- if ((await resumeUpdate({
394
- target,
395
- trust: {
396
- ...trust,
397
- channel
398
- },
399
- currentVersion: options.currentVersion
400
- }).catch((error) => {
401
- options.log(`update resume failed during health recovery: ${String(error)}`);
402
- return null;
403
- }))?.status !== "in-progress") break;
404
- const remaining = deadline - performance.now();
405
- if (remaining <= 0) {
406
- options.log("update helper remains active; health acknowledgement is deferred");
407
- break;
408
- }
409
- await Bun.sleep(Math.min(50, remaining));
389
+ const pendingHealthAcknowledgement = async () => {
390
+ let channel = selectedChannel;
391
+ try {
392
+ channel = releaseChannelForUpdate(await channelStore.read());
393
+ } catch (error) {
394
+ options.log(`update channel read failed during health recovery: ${String(error)}`);
395
+ }
396
+ const journal = await readUpdateStageState(updateStagingFor(target)).catch(() => void 0);
397
+ if (channel && !(journal?.phase === "staged" && journal.helperPid === void 0)) {
398
+ const deadline = performance.now() + HEALTH_ACK_HELPER_WAIT_MS;
399
+ for (;;) {
400
+ if ((await resumeUpdate({
401
+ target,
402
+ trust: {
403
+ ...trust,
404
+ channel
405
+ },
406
+ currentVersion: options.currentVersion
407
+ }).catch((error) => {
408
+ options.log(`update resume failed during health recovery: ${String(error)}`);
409
+ return null;
410
+ }))?.status !== "in-progress") break;
411
+ const remaining = deadline - performance.now();
412
+ if (remaining <= 0) {
413
+ options.log("update helper remains active; health acknowledgement is deferred");
414
+ break;
410
415
  }
416
+ await Bun.sleep(Math.min(50, remaining));
411
417
  }
412
- return findPendingUpdateHealthAcknowledgement({
418
+ }
419
+ return findPendingUpdateHealthAcknowledgement({
420
+ target,
421
+ currentVersion: options.currentVersion
422
+ });
423
+ };
424
+ let retention = Promise.resolve();
425
+ const maintainRetention = () => retention = retention.then(async () => {
426
+ try {
427
+ const lineage = await acknowledgeRetiredUpdateLineage({
428
+ target,
429
+ currentVersion: options.currentVersion
430
+ });
431
+ if (lineage) options.log(`recorded ${lineage} earlier update generation(s) as healthy`);
432
+ const result = await pruneRetiredUpdates({
413
433
  target,
414
434
  currentVersion: options.currentVersion
415
435
  });
436
+ if (result.pruned) options.log(`removed ${result.pruned} retired app copy(ies)`);
437
+ if (result.status === "recovery-required") options.log("retired app copies need recovery; they were preserved");
438
+ } catch (error) {
439
+ options.log(`retired app cleanup failed: ${String(error)}`);
440
+ }
441
+ });
442
+ const healthyAfterMs = options.healthyAfterMs ?? 6e4;
443
+ if (healthyAfterMs !== false) {
444
+ if (!Number.isSafeInteger(healthyAfterMs) || healthyAfterMs < 0) throw new Error("Invalid update health delay");
445
+ setTimeout(() => {
446
+ (async () => {
447
+ try {
448
+ const pending = await pendingHealthAcknowledgement();
449
+ if (pending) {
450
+ await acknowledgeRetiredUpdateHealthy({
451
+ target,
452
+ acknowledgement: pending
453
+ });
454
+ options.log(`acknowledged ${release.appName} ${pending.version} as healthy`);
455
+ }
456
+ } catch (error) {
457
+ options.log(`update health acknowledgement failed: ${String(error)}`);
458
+ }
459
+ await maintainRetention();
460
+ })();
461
+ }, healthyAfterMs).unref?.();
462
+ }
463
+ return createUpdater({
464
+ ...updater,
465
+ manager,
466
+ pendingHealthAcknowledgement,
467
+ async acknowledgeHealthy(acknowledgement) {
468
+ await acknowledgeRetiredUpdateHealthy({
469
+ target,
470
+ acknowledgement
471
+ });
472
+ maintainRetention();
416
473
  },
417
- acknowledgeHealthy: (acknowledgement) => acknowledgeRetiredUpdateHealthy({
418
- target,
419
- acknowledgement
420
- }),
421
474
  async restart(version) {
422
475
  await scheduleUpdateShutdown({
423
476
  reserve: () => ({}),
@@ -9,7 +9,8 @@ export type ReleaseFeed = Readonly<{
9
9
  base: string;
10
10
  app: string;
11
11
  }>;
12
- export type FeedChannel = 'dev' | 'daily' | 'stable';
12
+ /** The channels the feed publishes: release.json, channel pointers and signed descriptors. */
13
+ export type FeedChannel = 'daily' | 'stable';
13
14
  type FeedAsset = Readonly<{
14
15
  name: string;
15
16
  size: number;
@@ -26,7 +27,9 @@ export type FeedRelease = Readonly<{
26
27
  }>;
27
28
  export type LedgerEntry = Readonly<{
28
29
  tag: string;
29
- kind: FeedChannel;
30
+ /** `dev` is retired: older ledgers (Cortana's lists `v0.73.0-dev.3`) still hold dev builds,
31
+ * which are read but never published, promoted or followed. */
32
+ kind: FeedChannel | 'dev';
30
33
  version: string;
31
34
  sourceSha: string;
32
35
  publishedAt: string;
@@ -41,7 +44,7 @@ export type ReleaseLedger = Readonly<{
41
44
  }>;
42
45
  /** Ledger entries kept; the oldest fall off a full ledger. */
43
46
  export declare const MAX_LEDGER_RELEASES = 500;
44
- /** A release tag in the feed: `vX.Y.Z` or `vX.Y.Z-dev.N`. */
47
+ /** A release tag in the feed: `vX.Y.Z`, or `vX.Y.Z-dev.N` for a legacy ledger entry. */
45
48
  export declare const isFeedTag: (value: unknown) => value is string;
46
49
  export declare const isFeedAssetName: (value: unknown) => value is string;
47
50
  /** Validate a feed: an https origin and path prefix ending in `/`, with no credentials,
@@ -54,7 +57,7 @@ export declare function feedAssetKey(feed: ReleaseFeed, tag: string, name: strin
54
57
  export declare const feedReleaseKey: (feed: ReleaseFeed, tag: string) => string;
55
58
  export declare const feedIndexKey: (feed: ReleaseFeed) => string;
56
59
  export declare const feedChannelKey: (feed: ReleaseFeed, channel: FeedChannel) => string;
57
- /** Validate a release.json or channel pointer: a tag of its channel and a bounded,
60
+ /** Validate a release.json or channel pointer: a daily or stable release tag and a bounded,
58
61
  * unique asset inventory. */
59
62
  export declare function parseFeedRelease(value: unknown): FeedRelease;
60
63
  /** Validate the ledger: this app, at most MAX_LEDGER_RELEASES unique tags, newest first,
@@ -7,7 +7,7 @@ var exactKeys = (value, keys) => Object.keys(value).length === keys.length && ke
7
7
  var segment = /^[a-z0-9][a-z0-9-]{0,62}$/;
8
8
  var tagPattern = /^v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-dev\.[1-9]\d*)?$/;
9
9
  var timestamp = (value) => typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().replace(".000Z", "Z") === value.replace(".000Z", "Z");
10
- /** A release tag in the feed: `vX.Y.Z` or `vX.Y.Z-dev.N`. */
10
+ /** A release tag in the feed: `vX.Y.Z`, or `vX.Y.Z-dev.N` for a legacy ledger entry. */
11
11
  var isFeedTag = (value) => typeof value === "string" && value.length <= 65 && tagPattern.test(value);
12
12
  var isFeedAssetName = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(value);
13
13
  /** Validate a feed: an https origin and path prefix ending in `/`, with no credentials,
@@ -38,7 +38,7 @@ var feedReleaseKey = (feed, tag) => feedAssetKey(feed, tag, "release.json");
38
38
  var feedIndexKey = (feed) => `${feed.app}/index.json`;
39
39
  var feedChannelKey = (feed, channel) => `${feed.app}/channels/${channel}.json`;
40
40
  var channelOf = (tag) => tag.includes("-dev.") ? "dev" : "daily";
41
- /** Validate a release.json or channel pointer: a tag of its channel and a bounded,
41
+ /** Validate a release.json or channel pointer: a daily or stable release tag and a bounded,
42
42
  * unique asset inventory. */
43
43
  function parseFeedRelease(value) {
44
44
  if (!isRecord(value) || !exactKeys(value, Object.hasOwn(value, "missingPlatforms") ? [
@@ -52,11 +52,7 @@ function parseFeedRelease(value) {
52
52
  "channel",
53
53
  "publishedAt",
54
54
  "assets"
55
- ]) || !isFeedTag(value.tag) || ![
56
- "dev",
57
- "daily",
58
- "stable"
59
- ].includes(String(value.channel)) || value.channel === "dev" !== (channelOf(value.tag) === "dev") || !timestamp(value.publishedAt) || !Array.isArray(value.assets) || value.assets.length < 1 || value.assets.length > MAX_RELEASE_ASSETS) throw new Error("Invalid feed release");
55
+ ]) || !isFeedTag(value.tag) || value.channel !== "daily" && value.channel !== "stable" || channelOf(value.tag) === "dev" || !timestamp(value.publishedAt) || !Array.isArray(value.assets) || value.assets.length < 1 || value.assets.length > MAX_RELEASE_ASSETS) throw new Error("Invalid feed release");
60
56
  const names = /* @__PURE__ */ new Set();
61
57
  const assets = value.assets.map((asset) => {
62
58
  if (!isRecord(asset) || !exactKeys(asset, [
@@ -1,3 +1,4 @@
1
+ import { BoundedBodyError, readBoundedBytes } from "../../shared/bounded-body.js";
1
2
  import { discardStream } from "../../shared/discard-stream.js";
2
3
  // src/updates/feed/release-location.ts
3
4
  /** `value` as a URL inside `scope`: the same https origin, under its path prefix, with no
@@ -40,34 +41,13 @@ async function readReleaseBytes(response, maximum) {
40
41
  discardStream(response.body);
41
42
  throw new Error("Release feed request failed");
42
43
  }
43
- const length = response.headers.get("content-length");
44
- if (length !== null && (!/^\d+$/.test(length) || Number(length) > maximum)) {
45
- discardStream(response.body);
46
- throw new Error("Release feed response exceeds bound");
47
- }
48
- const reader = response.body.getReader(), chunks = [];
49
- let total = 0;
50
44
  try {
51
- for (;;) {
52
- const { value, done } = await reader.read();
53
- if (done) break;
54
- total += value.length;
55
- if (total > maximum) {
56
- discardStream(reader);
57
- throw new Error("Release feed response exceeds bound");
58
- }
59
- chunks.push(value);
60
- }
61
- } finally {
62
- reader.releaseLock();
63
- }
64
- const bytes = new Uint8Array(total);
65
- let offset = 0;
66
- for (const chunk of chunks) {
67
- bytes.set(chunk, offset);
68
- offset += chunk.length;
45
+ return await readBoundedBytes(response, maximum);
46
+ } catch (error) {
47
+ if (!(error instanceof BoundedBodyError)) throw error;
48
+ if (error.reason === "too-large") throw new Error("Release feed response exceeds bound", { cause: error });
49
+ throw error.cause ?? error;
69
50
  }
70
- return bytes;
71
51
  }
72
52
  /** Parse a 200 response of at most `maximum` bytes as UTF-8 JSON. */
73
53
  async function readReleaseJson(response, maximum) {
@@ -1,6 +1,11 @@
1
- /** The update channel an installation follows. */
2
- export type UpdateChannel = 'stable' | 'pre-release' | 'dev';
1
+ /** The update channel an installation follows: stable, or daily pre-release builds. */
2
+ export type UpdateChannel = 'stable' | 'pre-release';
3
3
  export declare function isUpdateChannel(value: unknown): value is UpdateChannel;
4
+ /**
5
+ * Read a channel from saved settings or a caller. The retired `dev` channel, which
6
+ * older installs saved and older channel pickers still send, reads as pre-release.
7
+ */
8
+ export declare function readUpdateChannel(value: unknown): UpdateChannel | null;
4
9
  /**
5
10
  * Semver ordering for everything the update grammar produces: `x.y.z` and the
6
11
  * dev builds `x.y.z-dev.N`. A dev build sorts below its own release
@@ -1,6 +1,13 @@
1
1
  // src/updates/feed/release-version.ts
2
2
  function isUpdateChannel(value) {
3
- return value === "stable" || value === "pre-release" || value === "dev";
3
+ return value === "stable" || value === "pre-release";
4
+ }
5
+ /**
6
+ * Read a channel from saved settings or a caller. The retired `dev` channel, which
7
+ * older installs saved and older channel pickers still send, reads as pre-release.
8
+ */
9
+ function readUpdateChannel(value) {
10
+ return value === "dev" ? "pre-release" : isUpdateChannel(value) ? value : null;
4
11
  }
5
12
  /**
6
13
  * Parse a version in the update grammar into `[major, minor, patch, dev]`,
@@ -62,4 +69,4 @@ function applicationVersion(env, fallback) {
62
69
  if (!isReleaseVersion(version)) throw new Error("Invalid application release version");
63
70
  return version;
64
71
  }
65
- export { applicationVersion, isReleaseTag, isReleaseVersion, isUpdateChannel, versionLessThan };
72
+ export { applicationVersion, isReleaseTag, isReleaseVersion, isUpdateChannel, readUpdateChannel, versionLessThan };
@@ -3,7 +3,7 @@ export type ReleaseDescriptor = Readonly<{
3
3
  schema: 2;
4
4
  appId: string;
5
5
  repository: string;
6
- channel: 'dev' | 'daily' | 'stable';
6
+ channel: 'daily' | 'stable';
7
7
  tag: string;
8
8
  version: string;
9
9
  sourceSha: string;
@@ -36,8 +36,8 @@ function valid(value) {
36
36
  if (!isRecord(value) || !exactKeys(value, keys) || !isRecord(value.asset) || !exactKeys(value.asset, assetKeys)) return false;
37
37
  if (value.schema !== 2 || typeof value.appId !== "string" || !/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/.test(value.appId) || value.appId.length > 255) return false;
38
38
  if (typeof value.repository !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.repository) || value.repository.length > 200) return false;
39
- if (value.channel !== "dev" && value.channel !== "daily" && value.channel !== "stable") return false;
40
- if (typeof value.version !== "string" || value.version.length > 64 || !/^\d+\.\d+\.\d+(?:-dev\.\d+)?$/.test(value.version) || value.tag !== `v${value.version}` || value.channel === "dev" !== /-dev\.\d+$/.test(value.version)) return false;
39
+ if (value.channel !== "daily" && value.channel !== "stable") return false;
40
+ if (typeof value.version !== "string" || value.version.length > 64 || !/^\d+\.\d+\.\d+$/.test(value.version) || value.tag !== `v${value.version}`) return false;
41
41
  if (typeof value.sourceSha !== "string" || !isGitSha(value.sourceSha) || typeof value.workflowSha !== "string" || !isGitSha(value.workflowSha)) return false;
42
42
  if (typeof value.runId !== "string" || !/^[1-9]\d{0,19}$/.test(value.runId) || !Number.isSafeInteger(value.runAttempt) || Number(value.runAttempt) < 1) return false;
43
43
  if (![
@@ -10,11 +10,7 @@ var MAX_LEDGER_BYTES = 1048576;
10
10
  async function discoverSignedRelease(options) {
11
11
  const { trust, discoveryName, olderThan } = options;
12
12
  const timeout = options.timeoutMs ?? 1e4;
13
- if (!trust || !isRepositorySlug(trust.repository) || ![
14
- "stable",
15
- "daily",
16
- "dev"
17
- ].includes(trust.channel) || typeof trust.feed !== "string" || typeof discoveryName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}\.json$/.test(discoveryName) || discoveryName === "release.json" || !Number.isSafeInteger(timeout) || timeout < 1 || timeout > 6e4) throw new Error("Invalid release discovery policy");
13
+ if (!trust || !isRepositorySlug(trust.repository) || !["stable", "daily"].includes(trust.channel) || typeof trust.feed !== "string" || typeof discoveryName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}\.json$/.test(discoveryName) || discoveryName === "release.json" || !Number.isSafeInteger(timeout) || timeout < 1 || timeout > 6e4) throw new Error("Invalid release discovery policy");
18
14
  const deadline = AbortSignal.timeout(timeout);
19
15
  const signal = options.signal ? AbortSignal.any([deadline, options.signal]) : deadline;
20
16
  const fetcher = options.fetch ?? globalThis.fetch;
@@ -25,7 +21,7 @@ async function discoverSignedRelease(options) {
25
21
  selected = parseFeedRelease(await readReleaseJson(await get(`channels/${trust.channel}.json`), MAX_POINTER_BYTES));
26
22
  if (selected.channel !== trust.channel) throw new Error("Invalid channel pointer");
27
23
  } else {
28
- const kinds = trust.channel === "stable" ? ["stable"] : trust.channel === "dev" ? ["dev"] : ["daily", "stable"];
24
+ const kinds = trust.channel === "stable" ? ["stable"] : ["daily", "stable"];
29
25
  const entry = parseReleaseLedger(await readReleaseJson(await get("index.json"), MAX_LEDGER_BYTES), new URL(trust.feed).pathname.split("/").at(-2)).releases.reduce((best, item) => kinds.includes(item.kind) && versionLessThan(item.tag, olderThan) && (!best || versionLessThan(best.tag, item.tag)) ? item : best, void 0);
30
26
  if (entry) {
31
27
  selected = parseFeedRelease(await readReleaseJson(await get(`${entry.tag}/release.json`), MAX_POINTER_BYTES));
@@ -1,86 +1,50 @@
1
- import { UUID_SOURCE, errorCode, isUuid } from "../../app/value-guards.js";
1
+ import { errorCode, hasExactOwnKeys, isUuid } from "../../app/value-guards.js";
2
2
  import { verifyReleaseDescriptor } from "../feed/signed-release.js";
3
- import { parseUpdateHelperRequest } from "./update-helper.js";
3
+ import { KNOWN_STAGING_ENTRIES, parseUpdateHelperRequest, stateTemporaryPattern } from "./update-helper.js";
4
4
  import { tryAcquireUpdateInstanceLease } from "../locks/update-instance-lease.js";
5
5
  import { tryAcquireUpdateLock } from "../locks/update-lock.js";
6
- import { readUpdateStageState, syncUpdateStageDirectory, writeUpdateStageStateDurably } from "../update-state-store.js";
6
+ import { readUpdateStageState, writeUpdateStageStateDurably } from "../update-state-store.js";
7
7
  import { readUpdateTreeIdentity, readUpdateTreeVersion, sameUpdateTreeDigest, sameUpdateTreeIdentity, syncUpdateTreeParent, updateStagingFor } from "../install/update-swap.js";
8
8
  import { readUpdateLaunchGate, tryAcquireUpdateHelperLiveness, tryRecoverUpdateLaunchGate } from "../launch/update-launch-gate.js";
9
9
  import { readUpdateMarker } from "../install/update-marker.js";
10
10
  import { readTreeDigestForProof } from "./resume-staging.js";
11
- import { lstat, open, readdir, realpath, rm, unlink } from "node:fs/promises";
11
+ import { readSmallStateFile } from "../locks/stable-file.js";
12
+ import { syncDirectory } from "../../shared/file-system.js";
13
+ import { lstat, readdir, realpath, rm, unlink } from "node:fs/promises";
12
14
  import { join } from "node:path";
13
- import { constants as constants$1 } from "node:fs";
14
15
  // src/updates/helper/launch-gate-recovery.ts
15
- var recoveryStagingEntries = /* @__PURE__ */ new Set([
16
- "candidate",
17
- "helper",
18
- "helper-armed",
19
- "helper-ready",
20
- "cancel.json",
21
- "cancel-ack.json",
22
- "request.json",
23
- "state.json"
24
- ]);
25
- function hasExactKeys(value, keys) {
26
- const actual = Object.keys(value).toSorted();
27
- const expected = keys.toSorted();
28
- return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
29
- }
30
- async function readOptionalRecoveryFile(path, maxBytes) {
31
- let info;
32
- try {
33
- info = await lstat(path);
34
- } catch (error) {
35
- if (errorCode(error) === "ENOENT") return void 0;
36
- throw error;
37
- }
38
- if (!info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > maxBytes) throw new Error("Invalid schema-3 helper recovery artifact");
39
- const file = await open(path, constants$1.O_RDONLY | (constants$1.O_NOFOLLOW ?? 0));
40
- try {
41
- const opened = await file.stat();
42
- if (!opened.isFile() || opened.size < 1 || opened.size > maxBytes) throw new Error("Invalid schema-3 helper recovery artifact");
43
- return await file.readFile("utf8");
44
- } finally {
45
- await file.close();
46
- }
16
+ /** Missing reads as undefined; a link, FIFO, non-file, empty or oversized artifact throws. */
17
+ function readOptionalRecoveryFile(path, maxBytes) {
18
+ return readSmallStateFile(path, maxBytes, "Invalid schema-3 helper recovery artifact");
47
19
  }
48
20
  async function recoveryInventoryIsKnown(staging, state) {
49
21
  const names = await readdir(staging);
50
- const stateTemporary = stateTemporaryPattern(state.generation);
51
- for (const name of names) {
52
- if (recoveryStagingEntries.has(name)) continue;
53
- if (!stateTemporary.test(name)) return false;
54
- const path = join(staging, name);
55
- const info = await lstat(path);
56
- if (!info.isFile() || info.isSymbolicLink() || info.size > 4096) return false;
57
- }
58
22
  if (!names.includes("candidate") || !names.includes("state.json")) return false;
23
+ const stateTemporary = stateTemporaryPattern(state.generation);
59
24
  for (const name of names) {
25
+ const temporary = stateTemporary.test(name);
26
+ if (!temporary && !KNOWN_STAGING_ENTRIES.has(name)) return false;
60
27
  const info = await lstat(join(staging, name));
61
- if (stateTemporary.test(name)) {
62
- if (!info.isFile() || info.isSymbolicLink()) return false;
63
- continue;
64
- }
65
- if (name === "candidate" || name === "helper") {
66
- if (!info.isDirectory() || info.isSymbolicLink()) return false;
67
- } else if (!info.isFile() || info.isSymbolicLink()) return false;
28
+ if (info.isSymbolicLink()) return false;
29
+ if (temporary) {
30
+ if (!info.isFile() || info.size > 4096) return false;
31
+ } else if (name === "candidate" || name === "helper" ? !info.isDirectory() : !info.isFile()) return false;
68
32
  }
69
33
  return true;
70
34
  }
71
- /** The temporary names `writeUpdateStageState` leaves for one generation's state file. */
72
- function stateTemporaryPattern(generation) {
73
- return new RegExp(`^\\.state-${generation}-${UUID_SOURCE}\\.tmp$`, "i");
74
- }
75
- async function isCanonicalRecoveryStaging(staging) {
76
- const info = await lstat(staging).catch((error) => {
35
+ /** A directory that is not a link; missing reads as false. */
36
+ async function isRealDirectory(path) {
37
+ const info = await lstat(path).catch((error) => {
77
38
  if (errorCode(error) === "ENOENT") return void 0;
78
39
  throw error;
79
40
  });
80
- return Boolean(info && info.isDirectory() && !info.isSymbolicLink() && await realpath(staging) === staging);
41
+ return Boolean(info?.isDirectory() && !info.isSymbolicLink());
42
+ }
43
+ async function isCanonicalRecoveryStaging(staging) {
44
+ return await isRealDirectory(staging) && await realpath(staging) === staging;
81
45
  }
82
46
  function recoveryMarkerMatches(value, keys, expected) {
83
- return Boolean(value && hasExactKeys(value, keys) && keys.every((key) => value[key] === expected[key]));
47
+ return Boolean(value && hasExactOwnKeys(value, keys) && keys.every((key) => value[key] === expected[key]));
84
48
  }
85
49
  async function helperDirectoryIsKnown(staging, state, gate, requestMayBeAbsent) {
86
50
  const helper = join(staging, "helper");
@@ -164,7 +128,7 @@ async function schema3RecoveryArtifactsMatch(target, staging, state, gate, reque
164
128
  } else try {
165
129
  const value = JSON.parse(requestText);
166
130
  const request = parseUpdateHelperRequest(value);
167
- if (typeof value !== "object" || value === null || Array.isArray(value) || !hasExactKeys(value, [
131
+ if (typeof value !== "object" || value === null || Array.isArray(value) || !hasExactOwnKeys(value, [
168
132
  "schema",
169
133
  "target",
170
134
  "platform",
@@ -242,14 +206,7 @@ function requestPlatformMatchesTrust(platform, trust) {
242
206
  async function schema3TreeLayout(target, staging, state) {
243
207
  if (!state.candidateTreeIdentity || !state.candidateTreeDigest || !state.previousTreeIdentity) return void 0;
244
208
  const candidate = join(staging, "candidate");
245
- const [targetInfo, candidateInfo] = await Promise.all([lstat(target).catch((error) => {
246
- if (errorCode(error) === "ENOENT") return void 0;
247
- throw error;
248
- }), lstat(candidate).catch((error) => {
249
- if (errorCode(error) === "ENOENT") return void 0;
250
- throw error;
251
- })]);
252
- if (!targetInfo || !targetInfo.isDirectory() || targetInfo.isSymbolicLink() || !candidateInfo || !candidateInfo.isDirectory() || candidateInfo.isSymbolicLink()) return void 0;
209
+ if (!(await Promise.all([isRealDirectory(target), isRealDirectory(candidate)])).every(Boolean)) return void 0;
253
210
  const [targetVersion, candidateVersion, targetIdentity, candidateIdentity] = await Promise.all([
254
211
  readUpdateTreeVersion(target),
255
212
  readUpdateTreeVersion(candidate),
@@ -321,14 +278,7 @@ async function removeFinalizationTemporaries(staging, names) {
321
278
  async function ownerlessStagedTreeMatches(target, staging, state) {
322
279
  if (!state.candidateTreeIdentity || !state.candidateTreeDigest) return false;
323
280
  const candidate = join(staging, "candidate");
324
- const [targetInfo, candidateInfo] = await Promise.all([lstat(target).catch((error) => {
325
- if (errorCode(error) === "ENOENT") return void 0;
326
- throw error;
327
- }), lstat(candidate).catch((error) => {
328
- if (errorCode(error) === "ENOENT") return void 0;
329
- throw error;
330
- })]);
331
- if (!targetInfo || !targetInfo.isDirectory() || targetInfo.isSymbolicLink() || !candidateInfo || !candidateInfo.isDirectory() || candidateInfo.isSymbolicLink()) return false;
281
+ if (!(await Promise.all([isRealDirectory(target), isRealDirectory(candidate)])).every(Boolean)) return false;
332
282
  const [targetVersion, candidateVersion, targetIdentity, candidateIdentity] = await Promise.all([
333
283
  readUpdateTreeVersion(target),
334
284
  readUpdateTreeVersion(candidate),
@@ -404,7 +354,7 @@ async function finalizeClearedSchema3StagedOwner(target, staging, trust) {
404
354
  await syncUpdateTreeParent(target);
405
355
  await syncUpdateTreeParent(join(staging, "candidate"));
406
356
  await removeFinalizationTemporaries(staging, temporaries);
407
- await syncUpdateStageDirectory(staging);
357
+ await syncDirectory(staging);
408
358
  return "absent";
409
359
  }
410
360
  if (!isUuid(state.generation) || !isUuid(state.launchGateOwner) || !isUuid(state.helperOwner ?? "") || !Number.isSafeInteger(state.helperPid) || (state.helperPid ?? 0) < 2) return "unreconciled";