@indigoai-us/hq-cloud 6.16.20 → 6.16.21

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 +544 -0
  50. package/dist/manifest/build-manifest.bench.test.js.map +1 -0
  51. package/dist/manifest/build-manifest.d.ts +319 -0
  52. package/dist/manifest/build-manifest.d.ts.map +1 -0
  53. package/dist/manifest/build-manifest.js +1043 -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 +1060 -0
  58. package/dist/manifest/build-manifest.test.js.map +1 -0
  59. package/dist/manifest/contract.d.ts +290 -0
  60. package/dist/manifest/contract.d.ts.map +1 -0
  61. package/dist/manifest/contract.js +476 -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 +283 -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 +143 -0
  76. package/dist/manifest/snapshot-store.d.ts.map +1 -0
  77. package/dist/manifest/snapshot-store.js +291 -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 +301 -0
  84. package/dist/manifest/upload-manifest.d.ts.map +1 -0
  85. package/dist/manifest/upload-manifest.js +921 -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 +1052 -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,143 @@
1
+ /**
2
+ * Per-scope manifest snapshot store (sync-reconciliation-audit US-002).
3
+ *
4
+ * The audit's client half uploads a manifest of every file in a scope. Doing
5
+ * that in FULL on every cycle is wasteful for a 70k-file HQ root, so the
6
+ * builder emits a DELTA against the last manifest it successfully produced.
7
+ * That "last manifest" lives here: one small JSON file per scope, holding the
8
+ * minimum needed to decide "changed / added / removed" — `hash`, `size`,
9
+ * `mtimeMs` per path. Nothing else is retained (no ledger metadata, no
10
+ * absolute paths), because anything more would be a second, drifting copy of
11
+ * state the journal already owns.
12
+ *
13
+ * Two design rules, both load-bearing:
14
+ *
15
+ * 1. **Reads NEVER throw.** A missing, truncated, half-written, or
16
+ * hand-edited snapshot must degrade to "no snapshot" → the builder emits
17
+ * a FULL manifest. A snapshot is a cache, and a cache that can break the
18
+ * feature it accelerates is worse than no cache.
19
+ * 2. **Writes are atomic (tmp + rename).** A crash mid-write must leave the
20
+ * previous snapshot intact rather than a truncated file that would be
21
+ * read as "no snapshot" (safe) or, worse, as a partial file list — which
22
+ * would manufacture a page of false `removedPaths` on the next delta.
23
+ */
24
+ import { type SyncManifestScope } from "./contract.js";
25
+ /** Directory (under the state dir) holding one JSON file per scope. */
26
+ export declare const MANIFEST_SNAPSHOT_DIRNAME = "manifest-snapshots";
27
+ /**
28
+ * A snapshot older than this is not trusted as a delta base: the longer it
29
+ * sits, the more likely the ledger, ignore rules, or the tree itself moved in
30
+ * ways a delta cannot express. Re-baselining weekly bounds how stale the
31
+ * server's picture of a scope can get without a full re-send.
32
+ */
33
+ export declare const MANIFEST_SNAPSHOT_MAX_AGE_MS: number;
34
+ /** The three fields a delta comparison needs, and nothing more. */
35
+ export interface ManifestSnapshotEntry {
36
+ hash: string;
37
+ size: number;
38
+ mtimeMs: number;
39
+ }
40
+ export interface ManifestSnapshot {
41
+ /** Opaque id; becomes `baseSnapshotId` on the next delta upload. */
42
+ snapshotId: string;
43
+ /** ISO-8601 UTC generation time — the input to the staleness check. */
44
+ generatedAt: string;
45
+ /** The `sequence` of the manifest this snapshot was captured from. */
46
+ sequence: number;
47
+ entries: Record<string, ManifestSnapshotEntry>;
48
+ /**
49
+ * ISO-8601 UTC time of the last manifest UPLOAD pass for this scope
50
+ * (US-004). Additive and optional: a snapshot written by an older build has
51
+ * no such field, and must read back as "never uploaded" rather than as a
52
+ * corrupt record — so this is validated leniently and simply dropped when it
53
+ * is not a parseable timestamp.
54
+ *
55
+ * It is deliberately kept HERE rather than in a second file: the throttle
56
+ * decision and the delta-base decision are read together on every pass, and
57
+ * two files would let them disagree after a partial write.
58
+ */
59
+ lastUploadAt?: string;
60
+ /**
61
+ * `false` marks this record as an UPLOAD BOOKKEEPING record only — its
62
+ * `entries` must NOT be used as a delta base (the server refused the fold,
63
+ * or asked for a full resend). Absent means `true`, which is what every
64
+ * pre-US-004 snapshot means.
65
+ *
66
+ * The reason this rides on the snapshot instead of deleting the file: the
67
+ * `sequence` and `lastUploadAt` on it are still load-bearing (sequence must
68
+ * never decrease, and the 24h throttle must still fire), and deleting the
69
+ * file would drop both.
70
+ */
71
+ baseValid?: boolean;
72
+ /**
73
+ * ISO-8601 UTC time of the last FAILED pass for this scope (US-004 failure
74
+ * backoff). Distinct from `lastUploadAt`, which records a pass that actually
75
+ * reached the server, because the two arm different gates: `lastUploadAt`
76
+ * spaces out healthy passes (24h), while this one — paired with
77
+ * {@link ManifestSnapshot.consecutiveFailures} — stops a broken endpoint from
78
+ * buying a full tree walk + hash on EVERY sync cycle.
79
+ *
80
+ * Additive and optional, validated leniently: an older build's snapshot has
81
+ * no such field and must read back as "no failures", not as corruption.
82
+ */
83
+ lastAttemptAt?: string;
84
+ /**
85
+ * How many passes in a row have failed without reaching the server. Drives
86
+ * the exponential retry floor; reset to absent by any pass the server
87
+ * answered (including a 404 soft skip or a `resend_full`), because those
88
+ * prove the endpoint is reachable.
89
+ */
90
+ consecutiveFailures?: number;
91
+ }
92
+ /**
93
+ * Stable per-scope key. `personal` and `company:{uid}` are deliberately
94
+ * different namespaces: a personal snapshot must never be reused as the delta
95
+ * base for a company scope (that would emit every company file as "removed"
96
+ * from the personal vault, and vice versa) — a tenant-boundary bug, not just
97
+ * a correctness one.
98
+ */
99
+ export declare function manifestSnapshotScopeKey(scope: SyncManifestScope): string;
100
+ /**
101
+ * Filename-safe form of a scope key. Every character outside `[A-Za-z0-9_-]`
102
+ * collapses to `_`, so a hostile or merely surprising companyUid can never
103
+ * escape the snapshot directory via `../` or a separator.
104
+ *
105
+ * That collapse is MANY-TO-ONE, and the contract's identifier rule admits
106
+ * `.` and `:` inside a companyUid — so `company:acme.eu` and `company:acme:eu`
107
+ * would otherwise sanitize to the SAME file and two tenants would share one
108
+ * delta base. Sharing a base across companies is a tenant-boundary bug: the
109
+ * second scope's delta would emit every file of the first as `removedPaths`.
110
+ * A digest of the RAW key is therefore appended, which is injective in
111
+ * practice while keeping the readable prefix for humans grepping the dir.
112
+ *
113
+ * {@link manifestSnapshotScopeSlug} is the extension-less form, reused by the
114
+ * upload pass to name its per-scope lock file — the same injectivity argument
115
+ * applies there, and for the same tenant-boundary reason: two scopes must
116
+ * never share one lock any more than they may share one delta base.
117
+ */
118
+ export declare function manifestSnapshotScopeSlug(scopeKey: string): string;
119
+ export declare function manifestSnapshotFileName(scopeKey: string): string;
120
+ export declare function manifestSnapshotPath(stateDir: string, scopeKey: string): string;
121
+ /** Generate an id that satisfies the contract's opaque-identifier validator. */
122
+ export declare function newManifestSnapshotId(): string;
123
+ /**
124
+ * Read the snapshot for a scope, or `null` when there is nothing usable.
125
+ *
126
+ * "Nothing usable" covers absence, unreadable files, invalid JSON, and any
127
+ * structurally wrong payload. All four collapse to the same safe outcome — a
128
+ * full manifest — so the caller never has to branch on why.
129
+ */
130
+ export declare function readManifestSnapshot(stateDir: string, scopeKey: string): ManifestSnapshot | null;
131
+ /** True when this snapshot's entries may be used as a delta base. */
132
+ export declare function isManifestSnapshotBaseUsable(snapshot: ManifestSnapshot): boolean;
133
+ /**
134
+ * Persist a snapshot atomically. Returns `false` on any failure.
135
+ *
136
+ * A failed write is deliberately NOT an error for the caller: the manifest it
137
+ * just built is still valid and still uploadable; the only consequence is
138
+ * that the next cycle re-sends a full manifest.
139
+ */
140
+ export declare function writeManifestSnapshot(stateDir: string, scopeKey: string, snapshot: ManifestSnapshot): boolean;
141
+ /** True when the snapshot is too old to be trusted as a delta base. */
142
+ export declare function isManifestSnapshotStale(snapshot: ManifestSnapshot, nowMs: number, maxAgeMs?: number): boolean;
143
+ //# sourceMappingURL=snapshot-store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../../src/manifest/snapshot-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE/E,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,uBAAuB,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAA0B,CAAC;AAEpE,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAQzE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAcD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA8EhG;AAED,qEAAqE;AACrE,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAEhF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAiBT;AAED,uEAAuE;AACvE,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAqC,GAC9C,OAAO,CAOT"}
@@ -0,0 +1,291 @@
1
+ /**
2
+ * Per-scope manifest snapshot store (sync-reconciliation-audit US-002).
3
+ *
4
+ * The audit's client half uploads a manifest of every file in a scope. Doing
5
+ * that in FULL on every cycle is wasteful for a 70k-file HQ root, so the
6
+ * builder emits a DELTA against the last manifest it successfully produced.
7
+ * That "last manifest" lives here: one small JSON file per scope, holding the
8
+ * minimum needed to decide "changed / added / removed" — `hash`, `size`,
9
+ * `mtimeMs` per path. Nothing else is retained (no ledger metadata, no
10
+ * absolute paths), because anything more would be a second, drifting copy of
11
+ * state the journal already owns.
12
+ *
13
+ * Two design rules, both load-bearing:
14
+ *
15
+ * 1. **Reads NEVER throw.** A missing, truncated, half-written, or
16
+ * hand-edited snapshot must degrade to "no snapshot" → the builder emits
17
+ * a FULL manifest. A snapshot is a cache, and a cache that can break the
18
+ * feature it accelerates is worse than no cache.
19
+ * 2. **Writes are atomic (tmp + rename).** A crash mid-write must leave the
20
+ * previous snapshot intact rather than a truncated file that would be
21
+ * read as "no snapshot" (safe) or, worse, as a partial file list — which
22
+ * would manufacture a page of false `removedPaths` on the next delta.
23
+ */
24
+ import * as crypto from "node:crypto";
25
+ import * as fs from "node:fs";
26
+ import * as path from "node:path";
27
+ import { assertSyncManifestPath } from "./contract.js";
28
+ /** Directory (under the state dir) holding one JSON file per scope. */
29
+ export const MANIFEST_SNAPSHOT_DIRNAME = "manifest-snapshots";
30
+ /**
31
+ * A snapshot older than this is not trusted as a delta base: the longer it
32
+ * sits, the more likely the ledger, ignore rules, or the tree itself moved in
33
+ * ways a delta cannot express. Re-baselining weekly bounds how stale the
34
+ * server's picture of a scope can get without a full re-send.
35
+ */
36
+ export const MANIFEST_SNAPSHOT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
37
+ /**
38
+ * Stable per-scope key. `personal` and `company:{uid}` are deliberately
39
+ * different namespaces: a personal snapshot must never be reused as the delta
40
+ * base for a company scope (that would emit every company file as "removed"
41
+ * from the personal vault, and vice versa) — a tenant-boundary bug, not just
42
+ * a correctness one.
43
+ */
44
+ export function manifestSnapshotScopeKey(scope) {
45
+ if (scope.kind === "company") {
46
+ if (!scope.companyUid) {
47
+ throw new Error("manifest snapshot: company scope requires a companyUid");
48
+ }
49
+ return `company:${scope.companyUid}`;
50
+ }
51
+ return "personal";
52
+ }
53
+ /**
54
+ * Filename-safe form of a scope key. Every character outside `[A-Za-z0-9_-]`
55
+ * collapses to `_`, so a hostile or merely surprising companyUid can never
56
+ * escape the snapshot directory via `../` or a separator.
57
+ *
58
+ * That collapse is MANY-TO-ONE, and the contract's identifier rule admits
59
+ * `.` and `:` inside a companyUid — so `company:acme.eu` and `company:acme:eu`
60
+ * would otherwise sanitize to the SAME file and two tenants would share one
61
+ * delta base. Sharing a base across companies is a tenant-boundary bug: the
62
+ * second scope's delta would emit every file of the first as `removedPaths`.
63
+ * A digest of the RAW key is therefore appended, which is injective in
64
+ * practice while keeping the readable prefix for humans grepping the dir.
65
+ *
66
+ * {@link manifestSnapshotScopeSlug} is the extension-less form, reused by the
67
+ * upload pass to name its per-scope lock file — the same injectivity argument
68
+ * applies there, and for the same tenant-boundary reason: two scopes must
69
+ * never share one lock any more than they may share one delta base.
70
+ */
71
+ export function manifestSnapshotScopeSlug(scopeKey) {
72
+ const cleaned = scopeKey.replace(/[^A-Za-z0-9_-]/g, "_");
73
+ if (!cleaned || /^[_-]+$/.test(cleaned)) {
74
+ throw new Error("manifest snapshot: scope key sanitizes to an empty identifier");
75
+ }
76
+ const digest = crypto.createHash("sha256").update(scopeKey, "utf8").digest("hex").slice(0, 16);
77
+ return `${cleaned.slice(0, 96)}-${digest}`;
78
+ }
79
+ export function manifestSnapshotFileName(scopeKey) {
80
+ return `${manifestSnapshotScopeSlug(scopeKey)}.json`;
81
+ }
82
+ export function manifestSnapshotPath(stateDir, scopeKey) {
83
+ return path.join(stateDir, MANIFEST_SNAPSHOT_DIRNAME, manifestSnapshotFileName(scopeKey));
84
+ }
85
+ /** Generate an id that satisfies the contract's opaque-identifier validator. */
86
+ export function newManifestSnapshotId() {
87
+ return `snap-${crypto.randomBytes(16).toString("hex")}`;
88
+ }
89
+ function isSnapshotEntry(value) {
90
+ if (value === null || typeof value !== "object" || Array.isArray(value))
91
+ return false;
92
+ const raw = value;
93
+ return (typeof raw.hash === "string" &&
94
+ typeof raw.size === "number" &&
95
+ Number.isFinite(raw.size) &&
96
+ typeof raw.mtimeMs === "number" &&
97
+ Number.isFinite(raw.mtimeMs));
98
+ }
99
+ /**
100
+ * Read the snapshot for a scope, or `null` when there is nothing usable.
101
+ *
102
+ * "Nothing usable" covers absence, unreadable files, invalid JSON, and any
103
+ * structurally wrong payload. All four collapse to the same safe outcome — a
104
+ * full manifest — so the caller never has to branch on why.
105
+ */
106
+ export function readManifestSnapshot(stateDir, scopeKey) {
107
+ let text;
108
+ try {
109
+ text = fs.readFileSync(manifestSnapshotPath(stateDir, scopeKey), "utf8");
110
+ }
111
+ catch {
112
+ return null;
113
+ }
114
+ let parsed;
115
+ try {
116
+ parsed = JSON.parse(text);
117
+ }
118
+ catch {
119
+ return null;
120
+ }
121
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
122
+ return null;
123
+ const raw = parsed;
124
+ if (typeof raw.snapshotId !== "string" || raw.snapshotId.length === 0)
125
+ return null;
126
+ if (typeof raw.generatedAt !== "string" || !Number.isFinite(Date.parse(raw.generatedAt)))
127
+ return null;
128
+ if (typeof raw.sequence !== "number" || !Number.isFinite(raw.sequence))
129
+ return null;
130
+ if (raw.entries === null || typeof raw.entries !== "object" || Array.isArray(raw.entries))
131
+ return null;
132
+ // Drop individual malformed rows rather than the whole snapshot: one bad
133
+ // row costs a single file a full re-send; discarding the snapshot costs a
134
+ // full re-send of the entire scope.
135
+ //
136
+ // The KEY is validated as strictly as the value, and for a sharper reason:
137
+ // these keys flow straight into the next delta's `removedPaths`, so a
138
+ // corrupt or hand-edited snapshot carrying an absolute path, a `../` escape
139
+ // or an over-long name would put that string on the wire as a claimed
140
+ // deletion. Validating here — with the contract's own path rule, not a
141
+ // second guess at it — means the builder can only ever emit removals it
142
+ // could also have emitted as entries.
143
+ //
144
+ // `Object.create(null)` rather than `{}`: a snapshot is untrusted JSON, and
145
+ // a literal would let a `__proto__` key mutate the object's prototype
146
+ // instead of adding a row.
147
+ const entries = Object.create(null);
148
+ for (const [key, value] of Object.entries(raw.entries)) {
149
+ if (!isSnapshotEntry(value))
150
+ continue;
151
+ try {
152
+ // Throws on an invalid path; the store's contract is to tolerate
153
+ // corruption by returning a clean subset, never to propagate it.
154
+ assertSyncManifestPath("path", key);
155
+ }
156
+ catch {
157
+ continue;
158
+ }
159
+ entries[key] = { hash: value.hash, size: value.size, mtimeMs: value.mtimeMs };
160
+ }
161
+ const snapshot = {
162
+ snapshotId: raw.snapshotId,
163
+ generatedAt: raw.generatedAt,
164
+ sequence: raw.sequence,
165
+ entries,
166
+ };
167
+ // Additive fields (US-004). A missing or malformed value degrades to the
168
+ // pre-US-004 meaning — never uploaded, base usable — rather than failing the
169
+ // whole read, which would cost a full re-send of the scope.
170
+ if (typeof raw.lastUploadAt === "string" && Number.isFinite(Date.parse(raw.lastUploadAt))) {
171
+ snapshot.lastUploadAt = raw.lastUploadAt;
172
+ }
173
+ if (typeof raw.baseValid === "boolean")
174
+ snapshot.baseValid = raw.baseValid;
175
+ if (typeof raw.lastAttemptAt === "string" && Number.isFinite(Date.parse(raw.lastAttemptAt))) {
176
+ snapshot.lastAttemptAt = raw.lastAttemptAt;
177
+ }
178
+ // A negative or fractional count would make the backoff exponent nonsense,
179
+ // and this file is untrusted JSON. Anything unusable degrades to "no
180
+ // failures" — the conservative reading, which retries sooner rather than
181
+ // wedging a healthy scope off the audit.
182
+ if (typeof raw.consecutiveFailures === "number" &&
183
+ Number.isSafeInteger(raw.consecutiveFailures) &&
184
+ raw.consecutiveFailures > 0) {
185
+ snapshot.consecutiveFailures = raw.consecutiveFailures;
186
+ }
187
+ return snapshot;
188
+ }
189
+ /** True when this snapshot's entries may be used as a delta base. */
190
+ export function isManifestSnapshotBaseUsable(snapshot) {
191
+ return snapshot.baseValid !== false;
192
+ }
193
+ /**
194
+ * Persist a snapshot atomically. Returns `false` on any failure.
195
+ *
196
+ * A failed write is deliberately NOT an error for the caller: the manifest it
197
+ * just built is still valid and still uploadable; the only consequence is
198
+ * that the next cycle re-sends a full manifest.
199
+ */
200
+ export function writeManifestSnapshot(stateDir, scopeKey, snapshot) {
201
+ const target = manifestSnapshotPath(stateDir, scopeKey);
202
+ const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
203
+ try {
204
+ fs.mkdirSync(path.dirname(target), { recursive: true });
205
+ writeSnapshotIncrementally(tmp, snapshot);
206
+ fs.renameSync(tmp, target);
207
+ return true;
208
+ }
209
+ catch {
210
+ try {
211
+ fs.rmSync(tmp, { force: true });
212
+ }
213
+ catch {
214
+ // Best effort; a stray tmp file is harmless and is overwritten by the
215
+ // next attempt's pid/timestamp-unique name.
216
+ }
217
+ return false;
218
+ }
219
+ }
220
+ /** True when the snapshot is too old to be trusted as a delta base. */
221
+ export function isManifestSnapshotStale(snapshot, nowMs, maxAgeMs = MANIFEST_SNAPSHOT_MAX_AGE_MS) {
222
+ const generatedMs = Date.parse(snapshot.generatedAt);
223
+ if (!Number.isFinite(generatedMs))
224
+ return true;
225
+ // A snapshot stamped in the FUTURE (clock skew, restored backup) is treated
226
+ // as stale too — its age is unknowable, so re-baseline rather than trust it.
227
+ if (generatedMs > nowMs)
228
+ return true;
229
+ return nowMs - generatedMs > maxAgeMs;
230
+ }
231
+ /**
232
+ * Serialise the snapshot to `tmp` INCREMENTALLY, a bounded batch of entries at
233
+ * a time.
234
+ *
235
+ * `JSON.stringify(snapshot)` builds one string holding the entire record
236
+ * before a single byte reaches the disk. On a 199k-entry scope that string is
237
+ * tens of megabytes of transient allocation, arriving at the moment the pass
238
+ * is already at its peak (the entry list, the ledger index and the snapshot
239
+ * map are all still live), so it lands squarely on the number the memory
240
+ * budget is measured against.
241
+ *
242
+ * Streaming the same bytes costs one batch instead. The output is byte-for-byte
243
+ * the JSON `JSON.stringify` would have produced for this shape — the top-level
244
+ * scalars first, then `entries` written key by key — so `readManifestSnapshot`
245
+ * is unchanged and an older reader parses it identically.
246
+ */
247
+ function writeSnapshotIncrementally(tmp, snapshot) {
248
+ const { entries, ...header } = snapshot;
249
+ const fd = fs.openSync(tmp, "w");
250
+ try {
251
+ // Batched, not per-entry: one `writeSync` per entry on a 199k-entry scope
252
+ // is 199k syscalls, which trades the memory win for a wall-clock loss.
253
+ let buffer = "";
254
+ const flush = (force) => {
255
+ if (!force && buffer.length < SNAPSHOT_WRITE_BATCH_CHARS)
256
+ return;
257
+ if (buffer.length === 0)
258
+ return;
259
+ fs.writeSync(fd, buffer, null, "utf8");
260
+ buffer = "";
261
+ };
262
+ // `JSON.stringify` on the header alone: it is a handful of scalars, and
263
+ // hand-rolling their escaping would be a needless second encoder.
264
+ const headerJson = JSON.stringify(header);
265
+ // `{...}` → `{...,"entries":{` — the header is never empty (`snapshotId`,
266
+ // `generatedAt` and `sequence` are required), so the comma is always right.
267
+ buffer += `${headerJson.slice(0, -1)},"entries":{`;
268
+ let first = true;
269
+ for (const key in entries) {
270
+ const entry = entries[key];
271
+ if (entry === undefined)
272
+ continue;
273
+ buffer += first ? "" : ",";
274
+ first = false;
275
+ buffer += `${JSON.stringify(key)}:${JSON.stringify(entry)}`;
276
+ flush(false);
277
+ }
278
+ buffer += "}}\n";
279
+ flush(true);
280
+ // Durability parity with the previous `writeFileSync` + `renameSync`: the
281
+ // rename is only atomic with respect to content that has actually reached
282
+ // the file.
283
+ fs.fsyncSync(fd);
284
+ }
285
+ finally {
286
+ fs.closeSync(fd);
287
+ }
288
+ }
289
+ /** Flush threshold for the incremental snapshot writer (characters, not bytes). */
290
+ const SNAPSHOT_WRITE_BATCH_CHARS = 256 * 1024;
291
+ //# sourceMappingURL=snapshot-store.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot-store.js","sourceRoot":"","sources":["../../src/manifest/snapshot-store.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Snapshot-store hardening regressions (US-002, Codex review).
3
+ *
4
+ * The store's contract is "tolerate corruption, return null or a clean
5
+ * subset" — it must never throw, and it must never hand the builder a row it
6
+ * would not have produced itself. That second half is the sharp edge: snapshot
7
+ * KEYS flow straight into the next delta's `removedPaths`, so a key the
8
+ * contract would reject is a claimed deletion the server cannot even parse.
9
+ */
10
+ export {};
11
+ //# sourceMappingURL=snapshot-store.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot-store.test.d.ts","sourceRoot":"","sources":["../../src/manifest/snapshot-store.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
@@ -0,0 +1,133 @@
1
+ /**
2
+ * Snapshot-store hardening regressions (US-002, Codex review).
3
+ *
4
+ * The store's contract is "tolerate corruption, return null or a clean
5
+ * subset" — it must never throw, and it must never hand the builder a row it
6
+ * would not have produced itself. That second half is the sharp edge: snapshot
7
+ * KEYS flow straight into the next delta's `removedPaths`, so a key the
8
+ * contract would reject is a claimed deletion the server cannot even parse.
9
+ */
10
+ import * as fs from "node:fs";
11
+ import * as os from "node:os";
12
+ import * as path from "node:path";
13
+ import { afterEach, beforeEach, describe, expect, it } from "vitest";
14
+ import { validateSyncManifestUpload } from "./contract.js";
15
+ import { buildSyncManifest } from "./build-manifest.js";
16
+ import { MANIFEST_SNAPSHOT_DIRNAME, manifestSnapshotPath, manifestSnapshotScopeKey, readManifestSnapshot, } from "./snapshot-store.js";
17
+ const NOW_MS = Date.parse("2026-09-04T12:00:00.000Z");
18
+ const VALID_ROW = { hash: "a".repeat(64), size: 1, mtimeMs: NOW_MS };
19
+ let hqRoot;
20
+ let stateDir;
21
+ beforeEach(() => {
22
+ const base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-snap-"));
23
+ hqRoot = path.join(base, "hq");
24
+ stateDir = path.join(base, "state");
25
+ fs.mkdirSync(hqRoot, { recursive: true });
26
+ fs.mkdirSync(stateDir, { recursive: true });
27
+ });
28
+ afterEach(() => {
29
+ fs.rmSync(path.dirname(hqRoot), { recursive: true, force: true });
30
+ });
31
+ /** Write a snapshot file BY HAND — the point is payloads the writer never emits. */
32
+ function writeRawSnapshot(scopeKey, entries) {
33
+ const target = manifestSnapshotPath(stateDir, scopeKey);
34
+ fs.mkdirSync(path.dirname(target), { recursive: true });
35
+ const payload = {
36
+ snapshotId: "snap-deadbeefdeadbeefdeadbeefdeadbeef",
37
+ generatedAt: new Date(NOW_MS - 60_000).toISOString(),
38
+ sequence: 6,
39
+ entries,
40
+ };
41
+ fs.writeFileSync(target, `${JSON.stringify(payload)}\n`, "utf8");
42
+ }
43
+ describe("readManifestSnapshot — key validation", () => {
44
+ it.each([
45
+ ["absolute", "/etc/passwd"],
46
+ ["parent escape", "../../etc/passwd"],
47
+ ["dot segment", "notes/./file.md"],
48
+ ["backslash separator", "notes\\file.md"],
49
+ ["drive letter", "C:/secrets.md"],
50
+ ["home relative", "~/secrets.md"],
51
+ ["trailing slash", "notes/"],
52
+ ["empty", ""],
53
+ ["NFD", "notes/cafe\u0301.md"],
54
+ ])("drops a %s key while keeping the valid rows", (_label, badKey) => {
55
+ writeRawSnapshot("personal", { [badKey]: VALID_ROW, "notes/keep.md": VALID_ROW });
56
+ const snapshot = readManifestSnapshot(stateDir, "personal");
57
+ expect(snapshot).not.toBeNull();
58
+ expect(Object.keys(snapshot?.entries ?? {})).toEqual(["notes/keep.md"]);
59
+ });
60
+ it("keeps a literal __proto__ row as an own property instead of mutating the object", () => {
61
+ // Built via `fromEntries` because `{ __proto__: … }` in a literal sets the
62
+ // prototype rather than creating the key we are trying to test.
63
+ writeRawSnapshot("personal", Object.fromEntries([
64
+ ["__proto__", VALID_ROW],
65
+ ["notes/keep.md", VALID_ROW],
66
+ ]));
67
+ const snapshot = readManifestSnapshot(stateDir, "personal");
68
+ // `__proto__` is a perfectly legal filename AND a legal contract path, so
69
+ // it must survive — as a ROW. On a `{}` literal the assignment would have
70
+ // been swallowed by the prototype setter instead.
71
+ expect(Object.prototype.hasOwnProperty.call(snapshot.entries, "__proto__")).toBe(true);
72
+ expect(Object.getPrototypeOf(snapshot.entries)).toBeNull();
73
+ // Nothing leaked onto the shared prototype.
74
+ expect(({}.hash)).toBeUndefined();
75
+ expect(Object.keys(snapshot.entries).sort()).toEqual(["__proto__", "notes/keep.md"]);
76
+ });
77
+ it("still returns null (never throws) for structurally broken payloads", () => {
78
+ const target = manifestSnapshotPath(stateDir, "personal");
79
+ fs.mkdirSync(path.dirname(target), { recursive: true });
80
+ fs.writeFileSync(target, "{not json", "utf8");
81
+ expect(readManifestSnapshot(stateDir, "personal")).toBeNull();
82
+ });
83
+ });
84
+ describe("buildSyncManifest — a corrupt snapshot cannot poison removedPaths", () => {
85
+ it("never emits an unrepresentable snapshot key as a removal", async () => {
86
+ fs.mkdirSync(path.join(hqRoot, "notes"), { recursive: true });
87
+ fs.writeFileSync(path.join(hqRoot, "notes", "keep.md"), "hello", "utf8");
88
+ writeRawSnapshot("personal", {
89
+ "/etc/passwd": VALID_ROW,
90
+ "../../escape.md": VALID_ROW,
91
+ "notes/gone.md": VALID_ROW,
92
+ });
93
+ const result = await buildSyncManifest({
94
+ scope: { kind: "personal" },
95
+ hqRoot,
96
+ stateDir,
97
+ installationId: "install-abc123",
98
+ machineId: "machine-abc123",
99
+ source: "cli",
100
+ sequence: 7,
101
+ now: NOW_MS,
102
+ listJournalsImpl: () => [],
103
+ });
104
+ expect(result.mode).toBe("delta");
105
+ // Only the genuinely deleted, genuinely representable path is claimed.
106
+ expect(result.chunks[0].removedPaths).toEqual(["notes/gone.md"]);
107
+ // And the chunk is something the server can actually parse — an absolute
108
+ // path in `removedPaths` fails the contract outright.
109
+ expect(() => validateSyncManifestUpload(result.chunks[0])).not.toThrow();
110
+ });
111
+ });
112
+ describe("manifestSnapshotPath — tenant isolation", () => {
113
+ it("gives two company scopes that sanitize alike DIFFERENT snapshot files", () => {
114
+ // The contract's identifier rule admits `.` and `:` inside a companyUid,
115
+ // and the filename sanitizer collapses both to `_`. Without a disambiguator
116
+ // these two tenants would share one delta base — and the second scope's
117
+ // delta would then claim every file of the first as `removedPaths`.
118
+ const first = manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "company", companyUid: "acme.eu" }));
119
+ const second = manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "company", companyUid: "acme:eu" }));
120
+ expect(first).not.toBe(second);
121
+ });
122
+ it("never lets a scope key escape the snapshot directory", () => {
123
+ const dir = path.join(stateDir, MANIFEST_SNAPSHOT_DIRNAME);
124
+ for (const uid of ["../../etc/passwd", "a/b", "a\\b", ".."]) {
125
+ const file = manifestSnapshotPath(stateDir, `company:${uid}`);
126
+ expect(path.dirname(file)).toBe(dir);
127
+ }
128
+ });
129
+ it("keeps personal and company scopes on separate files", () => {
130
+ expect(manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "personal" }))).not.toBe(manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "company", companyUid: "personal" })));
131
+ });
132
+ });
133
+ //# sourceMappingURL=snapshot-store.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"snapshot-store.test.js","sourceRoot":"","sources":["../../src/manifest/snapshot-store.test.ts"],"names":[],"mappings":"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"}