@indigoai-us/hq-cloud 6.16.20 → 6.16.22

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 (110) hide show
  1. package/dist/bin/sync-runner-installation-id.d.ts +66 -0
  2. package/dist/bin/sync-runner-installation-id.d.ts.map +1 -0
  3. package/dist/bin/sync-runner-installation-id.js +138 -0
  4. package/dist/bin/sync-runner-installation-id.js.map +1 -0
  5. package/dist/bin/sync-runner-manifest.d.ts +120 -0
  6. package/dist/bin/sync-runner-manifest.d.ts.map +1 -0
  7. package/dist/bin/sync-runner-manifest.js +348 -0
  8. package/dist/bin/sync-runner-manifest.js.map +1 -0
  9. package/dist/bin/sync-runner-manifest.test.d.ts +12 -0
  10. package/dist/bin/sync-runner-manifest.test.d.ts.map +1 -0
  11. package/dist/bin/sync-runner-manifest.test.js +510 -0
  12. package/dist/bin/sync-runner-manifest.test.js.map +1 -0
  13. package/dist/bin/sync-runner.d.ts +55 -0
  14. package/dist/bin/sync-runner.d.ts.map +1 -1
  15. package/dist/bin/sync-runner.js +69 -0
  16. package/dist/bin/sync-runner.js.map +1 -1
  17. package/dist/bin/sync-runner.test.js +217 -0
  18. package/dist/bin/sync-runner.test.js.map +1 -1
  19. package/dist/company-slug.d.ts +31 -0
  20. package/dist/company-slug.d.ts.map +1 -0
  21. package/dist/company-slug.js +52 -0
  22. package/dist/company-slug.js.map +1 -0
  23. package/dist/company-slug.test.d.ts +7 -0
  24. package/dist/company-slug.test.d.ts.map +1 -0
  25. package/dist/company-slug.test.js +43 -0
  26. package/dist/company-slug.test.js.map +1 -0
  27. package/dist/index.d.ts +2 -0
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +5 -0
  30. package/dist/index.js.map +1 -1
  31. package/dist/journal-ledger-index.test.d.ts +15 -0
  32. package/dist/journal-ledger-index.test.d.ts.map +1 -0
  33. package/dist/journal-ledger-index.test.js +247 -0
  34. package/dist/journal-ledger-index.test.js.map +1 -0
  35. package/dist/journal.d.ts +110 -0
  36. package/dist/journal.d.ts.map +1 -1
  37. package/dist/journal.js +253 -5
  38. package/dist/journal.js.map +1 -1
  39. package/dist/manifest/US-002.acceptance.test.d.ts +11 -0
  40. package/dist/manifest/US-002.acceptance.test.d.ts.map +1 -0
  41. package/dist/manifest/US-002.acceptance.test.js +160 -0
  42. package/dist/manifest/US-002.acceptance.test.js.map +1 -0
  43. package/dist/manifest/US-004.acceptance.test.d.ts +12 -0
  44. package/dist/manifest/US-004.acceptance.test.d.ts.map +1 -0
  45. package/dist/manifest/US-004.acceptance.test.js +173 -0
  46. package/dist/manifest/US-004.acceptance.test.js.map +1 -0
  47. package/dist/manifest/build-manifest.bench.test.d.ts +22 -0
  48. package/dist/manifest/build-manifest.bench.test.d.ts.map +1 -0
  49. package/dist/manifest/build-manifest.bench.test.js +563 -0
  50. package/dist/manifest/build-manifest.bench.test.js.map +1 -0
  51. package/dist/manifest/build-manifest.d.ts +355 -0
  52. package/dist/manifest/build-manifest.d.ts.map +1 -0
  53. package/dist/manifest/build-manifest.js +1139 -0
  54. package/dist/manifest/build-manifest.js.map +1 -0
  55. package/dist/manifest/build-manifest.test.d.ts +10 -0
  56. package/dist/manifest/build-manifest.test.d.ts.map +1 -0
  57. package/dist/manifest/build-manifest.test.js +1172 -0
  58. package/dist/manifest/build-manifest.test.js.map +1 -0
  59. package/dist/manifest/contract.d.ts +356 -0
  60. package/dist/manifest/contract.d.ts.map +1 -0
  61. package/dist/manifest/contract.js +542 -0
  62. package/dist/manifest/contract.js.map +1 -0
  63. package/dist/manifest/contract.test.d.ts +17 -0
  64. package/dist/manifest/contract.test.d.ts.map +1 -0
  65. package/dist/manifest/contract.test.js +304 -0
  66. package/dist/manifest/contract.test.js.map +1 -0
  67. package/dist/manifest/import-graph.test.d.ts +25 -0
  68. package/dist/manifest/import-graph.test.d.ts.map +1 -0
  69. package/dist/manifest/import-graph.test.js +120 -0
  70. package/dist/manifest/import-graph.test.js.map +1 -0
  71. package/dist/manifest/ledger-shard-isolation.test.d.ts +18 -0
  72. package/dist/manifest/ledger-shard-isolation.test.d.ts.map +1 -0
  73. package/dist/manifest/ledger-shard-isolation.test.js +153 -0
  74. package/dist/manifest/ledger-shard-isolation.test.js.map +1 -0
  75. package/dist/manifest/snapshot-store.d.ts +160 -0
  76. package/dist/manifest/snapshot-store.d.ts.map +1 -0
  77. package/dist/manifest/snapshot-store.js +300 -0
  78. package/dist/manifest/snapshot-store.js.map +1 -0
  79. package/dist/manifest/snapshot-store.test.d.ts +11 -0
  80. package/dist/manifest/snapshot-store.test.d.ts.map +1 -0
  81. package/dist/manifest/snapshot-store.test.js +133 -0
  82. package/dist/manifest/snapshot-store.test.js.map +1 -0
  83. package/dist/manifest/upload-manifest.d.ts +336 -0
  84. package/dist/manifest/upload-manifest.d.ts.map +1 -0
  85. package/dist/manifest/upload-manifest.js +1022 -0
  86. package/dist/manifest/upload-manifest.js.map +1 -0
  87. package/dist/manifest/upload-manifest.test.d.ts +10 -0
  88. package/dist/manifest/upload-manifest.test.d.ts.map +1 -0
  89. package/dist/manifest/upload-manifest.test.js +1116 -0
  90. package/dist/manifest/upload-manifest.test.js.map +1 -0
  91. package/dist/manifest-reconcile.d.ts.map +1 -1
  92. package/dist/manifest-reconcile.js +1 -26
  93. package/dist/manifest-reconcile.js.map +1 -1
  94. package/dist/posix-key.d.ts +36 -0
  95. package/dist/posix-key.d.ts.map +1 -0
  96. package/dist/posix-key.js +38 -0
  97. package/dist/posix-key.js.map +1 -0
  98. package/dist/s3.d.ts +2 -18
  99. package/dist/s3.d.ts.map +1 -1
  100. package/dist/s3.js +6 -20
  101. package/dist/s3.js.map +1 -1
  102. package/dist/sync/journal-ledger-stream.d.ts +56 -0
  103. package/dist/sync/journal-ledger-stream.d.ts.map +1 -0
  104. package/dist/sync/journal-ledger-stream.js +191 -0
  105. package/dist/sync/journal-ledger-stream.js.map +1 -0
  106. package/dist/sync/journal-ledger-stream.test.d.ts +12 -0
  107. package/dist/sync/journal-ledger-stream.test.d.ts.map +1 -0
  108. package/dist/sync/journal-ledger-stream.test.js +134 -0
  109. package/dist/sync/journal-ledger-stream.test.js.map +1 -0
  110. package/package.json +2 -1
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Resolve the DESKTOP installation identity that is actually enrolled in the
3
+ * client-health registry (US-004).
4
+ *
5
+ * WHY THIS EXISTS
6
+ * ---------------
7
+ * `POST /v1/sync-manifest/upload` is fenced on enrolment: hq-pro's
8
+ * `processSyncManifestUploadRequest` calls `isInstallationEnrolled(personUid,
9
+ * upload.installationId)`, which is
10
+ * `clientHealthStore.getSnapshot(personUid, installationId) !== null`. An
11
+ * installation id that no client-health heartbeat has ever reported gets a
12
+ * hard **403 INSTALLATION_NOT_ENROLLED** — the manifest row can never join the
13
+ * heartbeat row, so the whole audit is silently dead for that host.
14
+ *
15
+ * WHO ENROLS A DESKTOP HOST
16
+ * -------------------------
17
+ * Not hq-cloud: the sync engine sends no client-health heartbeat at all. The
18
+ * HQ Sync menubar app does, from Rust
19
+ * (`hq-desktop-app/apps/sync/src-tauri/src/commands/client_health.rs`). It
20
+ * pins its identity in `~/.hq/client-health.json` (`state_file_path()`), whose
21
+ * `ClientHealthState` is `#[serde(rename_all = "camelCase")]` — so the JSON
22
+ * key is `installationId`. The value is seeded on first use from
23
+ * `~/.hq/menubar.json`'s `machineId` when that is wire-shaped, else a fresh
24
+ * v4 UUID.
25
+ *
26
+ * That is NOT the same thing as `getOrCreateMachineId(hqRoot)`: machine-id
27
+ * resolves `HQ_MACHINE_ID` → `<hqRoot>/.hq/machine-id` → menubar `machineId` →
28
+ * autogen, and tier 2 wins before menubar ever gets a look-in. On a real
29
+ * install the two diverge (observed: enrolled `e1bff370-…` from menubar vs
30
+ * `<hqRoot>/.hq/machine-id` `e3ef5a5a-…`), which is exactly the 403.
31
+ *
32
+ * It is also NOT `cli-client-health.json`. That file is the hq-CLI's own
33
+ * separate enrolled installation (`hq-cli/src/utils/client-health.ts`,
34
+ * `CLIENT_HEALTH_STATE_FILE`); the CLI and the desktop are two distinct
35
+ * installations of one person and each enrols under its own id. The runner
36
+ * stamps `source: "desktop"`, so it must carry the DESKTOP id.
37
+ *
38
+ * DISCIPLINE
39
+ * ----------
40
+ * Strictly READ-ONLY. This module never creates, mints, migrates or rewrites
41
+ * the client-health state file. Minting an id here would (a) be unenrolled by
42
+ * construction, and (b) risk clobbering the heartbeat's own identity, which
43
+ * would orphan every previously-reported snapshot. It never throws: a missing,
44
+ * unreadable, malformed or non-conforming file is simply "no enrolled identity
45
+ * known", and the caller skips the upload.
46
+ */
47
+ /**
48
+ * The desktop app's client-health state file. Note the absence of the `cli-`
49
+ * prefix: `cli-client-health.json` is a DIFFERENT file owned by hq-cli for its
50
+ * own separately-enrolled installation.
51
+ */
52
+ export declare const DESKTOP_CLIENT_HEALTH_STATE_FILE = "client-health.json";
53
+ export interface ReadDesktopInstallationIdOptions {
54
+ /** The runner's state dir (`HQ_STATE_DIR`-aware). */
55
+ stateDir: string;
56
+ /** Injected home dir. Tests pin it; production reads `os.homedir()`. */
57
+ homeDir?: string;
58
+ }
59
+ /**
60
+ * The enrolled desktop installation id for this host, or `undefined` when no
61
+ * client-health heartbeat has ever pinned one.
62
+ *
63
+ * Never throws and never writes.
64
+ */
65
+ export declare function readDesktopInstallationId(options: ReadDesktopInstallationIdOptions): string | undefined;
66
+ //# sourceMappingURL=sync-runner-installation-id.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync-runner-installation-id.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner-installation-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAMH;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,uBAAuB,CAAC;AA0CrE,MAAM,WAAW,gCAAgC;IAC/C,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,MAAM,GAAG,SAAS,CA8BpB"}
@@ -0,0 +1,138 @@
1
+ /**
2
+ * Resolve the DESKTOP installation identity that is actually enrolled in the
3
+ * client-health registry (US-004).
4
+ *
5
+ * WHY THIS EXISTS
6
+ * ---------------
7
+ * `POST /v1/sync-manifest/upload` is fenced on enrolment: hq-pro's
8
+ * `processSyncManifestUploadRequest` calls `isInstallationEnrolled(personUid,
9
+ * upload.installationId)`, which is
10
+ * `clientHealthStore.getSnapshot(personUid, installationId) !== null`. An
11
+ * installation id that no client-health heartbeat has ever reported gets a
12
+ * hard **403 INSTALLATION_NOT_ENROLLED** — the manifest row can never join the
13
+ * heartbeat row, so the whole audit is silently dead for that host.
14
+ *
15
+ * WHO ENROLS A DESKTOP HOST
16
+ * -------------------------
17
+ * Not hq-cloud: the sync engine sends no client-health heartbeat at all. The
18
+ * HQ Sync menubar app does, from Rust
19
+ * (`hq-desktop-app/apps/sync/src-tauri/src/commands/client_health.rs`). It
20
+ * pins its identity in `~/.hq/client-health.json` (`state_file_path()`), whose
21
+ * `ClientHealthState` is `#[serde(rename_all = "camelCase")]` — so the JSON
22
+ * key is `installationId`. The value is seeded on first use from
23
+ * `~/.hq/menubar.json`'s `machineId` when that is wire-shaped, else a fresh
24
+ * v4 UUID.
25
+ *
26
+ * That is NOT the same thing as `getOrCreateMachineId(hqRoot)`: machine-id
27
+ * resolves `HQ_MACHINE_ID` → `<hqRoot>/.hq/machine-id` → menubar `machineId` →
28
+ * autogen, and tier 2 wins before menubar ever gets a look-in. On a real
29
+ * install the two diverge (observed: enrolled `e1bff370-…` from menubar vs
30
+ * `<hqRoot>/.hq/machine-id` `e3ef5a5a-…`), which is exactly the 403.
31
+ *
32
+ * It is also NOT `cli-client-health.json`. That file is the hq-CLI's own
33
+ * separate enrolled installation (`hq-cli/src/utils/client-health.ts`,
34
+ * `CLIENT_HEALTH_STATE_FILE`); the CLI and the desktop are two distinct
35
+ * installations of one person and each enrols under its own id. The runner
36
+ * stamps `source: "desktop"`, so it must carry the DESKTOP id.
37
+ *
38
+ * DISCIPLINE
39
+ * ----------
40
+ * Strictly READ-ONLY. This module never creates, mints, migrates or rewrites
41
+ * the client-health state file. Minting an id here would (a) be unenrolled by
42
+ * construction, and (b) risk clobbering the heartbeat's own identity, which
43
+ * would orphan every previously-reported snapshot. It never throws: a missing,
44
+ * unreadable, malformed or non-conforming file is simply "no enrolled identity
45
+ * known", and the caller skips the upload.
46
+ */
47
+ import * as fs from "node:fs";
48
+ import * as os from "node:os";
49
+ import * as path from "node:path";
50
+ /**
51
+ * The desktop app's client-health state file. Note the absence of the `cli-`
52
+ * prefix: `cli-client-health.json` is a DIFFERENT file owned by hq-cli for its
53
+ * own separately-enrolled installation.
54
+ */
55
+ export const DESKTOP_CLIENT_HEALTH_STATE_FILE = "client-health.json";
56
+ /**
57
+ * The manifest contract's identifier shape (`IDENTIFIER` in
58
+ * `src/manifest/contract.ts`, bounded by `SYNC_MANIFEST_MAX_ID_LENGTH`).
59
+ * Re-asserted here so a hand-edited state file is rejected as "not enrolled"
60
+ * rather than thrown out later by the contract mid-upload.
61
+ */
62
+ const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9_.:-]{1,63}$/;
63
+ /**
64
+ * Candidate locations for the desktop state file, **`~/.hq` FIRST**.
65
+ *
66
+ * The order matters and is the opposite of the intuitive one. The only writer
67
+ * of this file is the menubar app's Rust heartbeat, and it hard-codes
68
+ * `home_dir()/.hq` — it does not consult `HQ_STATE_DIR`. So `~/.hq` holds the
69
+ * id the SERVER has actually enrolled, and that is the only id an upload can
70
+ * succeed under.
71
+ *
72
+ * A copy under a relocated `HQ_STATE_DIR` is therefore either the same value
73
+ * (harmless) or a STALE one left behind by an earlier relocation — and
74
+ * preferring the stale copy is a silent, permanent 403 for the host, because
75
+ * the enrolment fence has no way to know the client meant the other id. When
76
+ * the two disagree, the enrolled one wins.
77
+ *
78
+ * The state dir is still consulted, second: on a host where the operator
79
+ * relocated state before the heartbeat ever ran, it is the only copy there is,
80
+ * and finding it beats skipping the audit. Duplicates collapse — the common
81
+ * case is one path.
82
+ */
83
+ function candidatePaths(stateDir, homeDir) {
84
+ const seen = new Set();
85
+ const out = [];
86
+ for (const dir of [path.join(homeDir, ".hq"), stateDir]) {
87
+ const file = path.join(dir, DESKTOP_CLIENT_HEALTH_STATE_FILE);
88
+ if (seen.has(file))
89
+ continue;
90
+ seen.add(file);
91
+ out.push(file);
92
+ }
93
+ return out;
94
+ }
95
+ /**
96
+ * The enrolled desktop installation id for this host, or `undefined` when no
97
+ * client-health heartbeat has ever pinned one.
98
+ *
99
+ * Never throws and never writes.
100
+ */
101
+ export function readDesktopInstallationId(options) {
102
+ let homeDir;
103
+ try {
104
+ homeDir = options.homeDir ?? os.homedir();
105
+ }
106
+ catch {
107
+ homeDir = options.stateDir;
108
+ }
109
+ for (const file of candidatePaths(options.stateDir, homeDir)) {
110
+ let raw;
111
+ try {
112
+ raw = fs.readFileSync(file, "utf8");
113
+ }
114
+ catch {
115
+ // Missing, a directory, or unreadable — try the next candidate.
116
+ continue;
117
+ }
118
+ let parsed;
119
+ try {
120
+ parsed = JSON.parse(raw);
121
+ }
122
+ catch {
123
+ // Corrupt/truncated file (e.g. a half-written stage that lost its
124
+ // rename). Not an error here: the heartbeat owns repairing it.
125
+ continue;
126
+ }
127
+ if (typeof parsed !== "object" || parsed === null)
128
+ continue;
129
+ const value = parsed.installationId;
130
+ if (typeof value !== "string")
131
+ continue;
132
+ if (!IDENTIFIER.test(value))
133
+ continue;
134
+ return value;
135
+ }
136
+ return undefined;
137
+ }
138
+ //# sourceMappingURL=sync-runner-installation-id.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync-runner-installation-id.js","sourceRoot":"","sources":["../../src/bin/sync-runner-installation-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,oBAAoB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,UAAU,GAAG,oCAAoC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,cAAc,CAAC,QAAgB,EAAE,OAAe;IACvD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gCAAgC,CAAC,CAAC;QAC9D,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAyC;IAEzC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC7B,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;QAC7D,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;YAChE,SAAS;QACX,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,+DAA+D;YAC/D,SAAS;QACX,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC5D,MAAM,KAAK,GAAI,MAAuC,CAAC,cAAc,CAAC;QACtE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QACxC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Desktop-daemon hook for the sync-reconciliation audit (US-004).
3
+ *
4
+ * WHY THIS LIVES IN THE RUNNER
5
+ * ----------------------------
6
+ * The HQ Sync desktop app does not run a sync pass itself — it spawns
7
+ * `hq-sync-runner` and consumes its ndjson. So "after a successful sync pass
8
+ * the desktop daemon uploads a manifest" IS a runner concern: the runner is
9
+ * the only process that knows which scopes were synced, which of them finished
10
+ * CLEANLY, where the HQ root and the state dir are, and how to mint a JWT.
11
+ *
12
+ * WHAT THIS OWNS (and nothing more)
13
+ * ---------------------------------
14
+ * - picking the scopes that earned an upload (clean pass only);
15
+ * - resolving the installation/machine identity;
16
+ * - the authed transport (base URL + bearer);
17
+ * - turning each pass result into one additive ndjson event.
18
+ *
19
+ * Everything that makes an upload SAFE — the kill switch, the 24h per-scope
20
+ * throttle, sequencing, chunking, the delta base, the 404 soft skip and the
21
+ * upload wall clock — belongs to `runManifestUploadPass` and is deliberately
22
+ * NOT re-derived here.
23
+ *
24
+ * FAILURE POSTURE
25
+ * ---------------
26
+ * This is a tail step: it runs AFTER `all-complete` has been emitted, and it
27
+ * can never change the runner's exit code or any pre-existing event. An audit
28
+ * that can break sync is strictly worse than no audit, so every call site is
29
+ * wrapped and every outcome — including a throwing or hanging transport — ends
30
+ * as a diagnostic plus (where a pass ran) one `manifest-upload` event.
31
+ */
32
+ import { type ManifestUploadPassStatus, type RunManifestUploadPassOptions, type RunManifestUploadPassResult } from "../manifest/upload-manifest.js";
33
+ import type { RunnerTarget } from "./sync-runner-planning.js";
34
+ /**
35
+ * Wall-clock bound on the tree WALK for one scope.
36
+ *
37
+ * Separate from the seam's upload budget (a slow disk and a black-holed socket
38
+ * fail for unrelated reasons).
39
+ *
40
+ * Was 30s, which measured as far too tight: on a real 690k-file personal vault
41
+ * the walk expired after ~179k files, and (before the truncation guard landed)
42
+ * uploaded the resulting empty manifest as a complete one. The stat walk
43
+ * benches at well under 2s per 70k files, so ~690k files wants ~20s of pure
44
+ * stat — but a cold page cache, a spinning disk or a busy laptop can multiply
45
+ * that several times over, and the cost of over-budgeting is nil (the walk
46
+ * yields to the event loop throughout and stops the moment it finishes) while
47
+ * the cost of under-budgeting is a scope that can NEVER complete a pass.
48
+ * 90s gives roughly 4x headroom over the measured target.
49
+ */
50
+ export declare const RUNNER_MANIFEST_WALK_WALL_MS = 90000;
51
+ /**
52
+ * Bound on the ENTIRE post-sync manifest phase, across every scope.
53
+ *
54
+ * The per-scope budgets already bound each pass, but a wide fanout multiplies
55
+ * them. This is the promise the runner makes to its supervisor: the tail step
56
+ * is over within a bounded time no matter how many companies are in the plan.
57
+ */
58
+ export declare const RUNNER_MANIFEST_PHASE_WALL_MS = 240000;
59
+ /**
60
+ * One scope's outcome, as the desktop app and the logs see it.
61
+ *
62
+ * Numbers and fixed tokens only — never a path, filename, or error message.
63
+ */
64
+ export interface ManifestUploadEventPayload {
65
+ /** Company slug, or `"personal"` for the personal vault leg. */
66
+ company: string;
67
+ scope: "personal" | "company";
68
+ status: ManifestUploadPassStatus;
69
+ mode?: "full" | "delta";
70
+ chunkCount?: number;
71
+ uploadedChunks?: number;
72
+ /** Failure CLASS token (never a message). Present only for `failed`. */
73
+ errorKind?: string;
74
+ }
75
+ export interface RunPostSyncManifestUploadsOptions {
76
+ hqRoot: string;
77
+ stateDir: string;
78
+ /** The fanout plan, in fanout order. */
79
+ targets: readonly RunnerTarget[];
80
+ /** Slugs whose leg returned cleanly with `aborted: false` and no error. */
81
+ completedCompanySlugs: ReadonlySet<string>;
82
+ /** Vault API base URL (the runner's `DEFAULT_VAULT_API_URL`). */
83
+ apiBaseUrl: string;
84
+ getAccessToken: () => Promise<string>;
85
+ /** Client name/version stamped on every request, like the vault client. */
86
+ clientInfo?: {
87
+ name: string;
88
+ version: string;
89
+ };
90
+ /** One `manifest-upload` ndjson event per scope that actually ran a pass. */
91
+ emitEvent: (payload: ManifestUploadEventPayload) => void;
92
+ reportDiagnostic?: (diagnostic: {
93
+ event: string;
94
+ message: string;
95
+ err?: unknown;
96
+ context?: Record<string, unknown>;
97
+ }) => void;
98
+ /** Injected env — tests pin it; production reads `process.env`. */
99
+ env?: NodeJS.ProcessEnv;
100
+ /** Injected clock (epoch ms), forwarded to the pass. Tests pin it. */
101
+ now?: number;
102
+ /** Test seam: stands in for `runManifestUploadPass`. */
103
+ runPass?: (options: RunManifestUploadPassOptions) => Promise<RunManifestUploadPassResult>;
104
+ /** Test seam: stands in for the global `fetch`. */
105
+ fetchImpl?: typeof fetch;
106
+ /** Test seam: stands in for `getOrCreateMachineId`. */
107
+ resolveMachineId?: (hqRoot: string) => string;
108
+ /** Test seam: stands in for `readDesktopInstallationId`. */
109
+ resolveInstallationId?: (options: {
110
+ stateDir: string;
111
+ }) => string | undefined;
112
+ }
113
+ /**
114
+ * Run one manifest upload pass per cleanly-synced scope.
115
+ *
116
+ * Never throws, never rejects: the caller is a tail step whose only contract
117
+ * is that the runner's exit code and event stream are unchanged by it.
118
+ */
119
+ export declare function runPostSyncManifestUploads(options: RunPostSyncManifestUploadsOptions): Promise<ManifestUploadEventPayload[]>;
120
+ //# sourceMappingURL=sync-runner-manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync-runner-manifest.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,EAGL,KAAK,wBAAwB,EAE7B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EACjC,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAKrD;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,wBAAwB,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iCAAiC;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,2EAA2E;IAC3E,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3C,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAC3E,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,6EAA6E;IAC7E,SAAS,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACzD,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE;QAC9B,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,KAAK,IAAI,CAAC;IACX,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,4BAA4B,KAClC,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC1C,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE;QAChC,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,MAAM,GAAG,SAAS,CAAC;CAC1B;AA+GD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAuMvC"}