@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,153 @@
1
+ /**
2
+ * The manifest build reads ONE journal shard: the one describing its scope.
3
+ *
4
+ * This is a memory invariant expressed as a behavioural one. `listJournals()`
5
+ * reads and parses every shard on the machine, and on a laptop holding a
6
+ * personal vault plus several cloud companies that was the single largest line
7
+ * item in the tail step's footprint — hundreds of megabytes spent parsing
8
+ * ledgers whose rows were then dropped on the floor, repaid once per scope in
9
+ * a fanout.
10
+ *
11
+ * A byte counter would be the obvious gate and the wrong one: it moves with
12
+ * fixture size and tempts a future reader to widen it. The thing that must not
13
+ * come back is the ENUMERATION, so the assertion counts journal files opened.
14
+ * One is correct; anything above one means a caller has gone back to reading
15
+ * the machine instead of the scope, no matter what the megabytes say.
16
+ */
17
+ import * as os from "node:os";
18
+ import * as path from "node:path";
19
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
20
+ /**
21
+ * Journal reads reach the filesystem through two specifiers — `journal.ts`
22
+ * imports `"fs"` and the streaming ledger reader imports `"node:fs"` — and a
23
+ * counter that watches only one of them would report a comfortable "1" while
24
+ * the other quietly read the whole state dir. Both are instrumented, and the
25
+ * counts are keyed by resolved path so a shard opened twice through different
26
+ * specifiers is still one shard.
27
+ */
28
+ const opened = vi.hoisted(() => ({ paths: [] }));
29
+ function recordIfJournal(target) {
30
+ const value = String(target);
31
+ if (/sync-journal\..*\.json$/.test(value))
32
+ opened.paths.push(value);
33
+ }
34
+ vi.mock("node:fs", async (importOriginal) => {
35
+ const actual = await importOriginal();
36
+ return {
37
+ ...actual,
38
+ default: actual,
39
+ openSync: ((target, ...rest) => {
40
+ recordIfJournal(target);
41
+ return actual.openSync(target, ...rest);
42
+ }),
43
+ readFileSync: ((target, ...rest) => {
44
+ recordIfJournal(target);
45
+ return actual.readFileSync(target, ...rest);
46
+ }),
47
+ };
48
+ });
49
+ vi.mock("fs", async (importOriginal) => {
50
+ const actual = await importOriginal();
51
+ return {
52
+ ...actual,
53
+ default: actual,
54
+ openSync: ((target, ...rest) => {
55
+ recordIfJournal(target);
56
+ return actual.openSync(target, ...rest);
57
+ }),
58
+ readFileSync: ((target, ...rest) => {
59
+ recordIfJournal(target);
60
+ return actual.readFileSync(target, ...rest);
61
+ }),
62
+ };
63
+ });
64
+ const fs = await import("node:fs");
65
+ const { buildSyncManifest } = await import("./build-manifest.js");
66
+ const { PERSONAL_VAULT_JOURNAL_SLUG } = await import("../journal.js");
67
+ const OTHER_SLUGS = ["acme", "globex", "initech"];
68
+ let base;
69
+ let hqRoot;
70
+ let stateDir;
71
+ let previousStateDir;
72
+ function writeShard(slug, files) {
73
+ fs.writeFileSync(path.join(stateDir, `sync-journal.${slug}.json`), JSON.stringify({ version: "2", files, pulls: [] }), "utf8");
74
+ }
75
+ function ledgerRow(index) {
76
+ return {
77
+ hash: `sha256:${index.toString(16).padStart(64, "0")}`,
78
+ size: 100 + index,
79
+ syncedAt: "2026-01-01T00:00:00.000Z",
80
+ direction: "up",
81
+ };
82
+ }
83
+ beforeEach(() => {
84
+ base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-shard-isolation-"));
85
+ hqRoot = path.join(base, "hq");
86
+ stateDir = path.join(base, "state");
87
+ fs.mkdirSync(stateDir, { recursive: true });
88
+ fs.mkdirSync(path.join(hqRoot, "notes"), { recursive: true });
89
+ fs.writeFileSync(path.join(hqRoot, "notes", "kept.md"), "kept\n");
90
+ writeShard(PERSONAL_VAULT_JOURNAL_SLUG, {
91
+ "notes/kept.md": ledgerRow(1),
92
+ "notes/gone.md": ledgerRow(2),
93
+ });
94
+ // Present only so they can be NOT read. Each carries a row that would be
95
+ // unmistakable if it leaked into the personal manifest.
96
+ OTHER_SLUGS.forEach((slug, index) => {
97
+ writeShard(slug, { [`${slug}/secret-${index}.md`]: ledgerRow(100 + index) });
98
+ });
99
+ previousStateDir = process.env.HQ_STATE_DIR;
100
+ process.env.HQ_STATE_DIR = stateDir;
101
+ opened.paths = [];
102
+ });
103
+ afterEach(() => {
104
+ if (previousStateDir === undefined)
105
+ delete process.env.HQ_STATE_DIR;
106
+ else
107
+ process.env.HQ_STATE_DIR = previousStateDir;
108
+ fs.rmSync(base, { recursive: true, force: true });
109
+ });
110
+ describe("buildSyncManifest — the ledger read is scoped to one shard", () => {
111
+ it("opens the scope's journal file and no other", async () => {
112
+ const result = await buildSyncManifest({
113
+ scope: { kind: "personal" },
114
+ hqRoot,
115
+ stateDir,
116
+ installationId: "install-shard",
117
+ machineId: "machine-shard",
118
+ source: "cli",
119
+ sequence: 1,
120
+ hashPolicy: "never",
121
+ maxWallMs: 60_000,
122
+ persistSnapshot: false,
123
+ });
124
+ const distinct = [...new Set(opened.paths)];
125
+ expect(distinct).toEqual([path.join(stateDir, `sync-journal.${PERSONAL_VAULT_JOURNAL_SLUG}.json`)]);
126
+ // The count is only meaningful if the shard was actually USED: a read that
127
+ // returns nothing also opens nothing.
128
+ const reported = result.chunks.flatMap((chunk) => chunk.entries);
129
+ expect(reported.map((entry) => entry.path).sort()).toEqual(["notes/gone.md", "notes/kept.md"]);
130
+ // And nothing from a neighbouring tenant's shard came along for the ride.
131
+ expect(reported.some((entry) => entry.path.includes("secret-"))).toBe(false);
132
+ });
133
+ it("stays at one shard as the machine accumulates more companies", async () => {
134
+ for (let index = 0; index < 12; index += 1) {
135
+ writeShard(`extra-${index}`, { [`extra-${index}/a.md`]: ledgerRow(index) });
136
+ }
137
+ opened.paths = [];
138
+ await buildSyncManifest({
139
+ scope: { kind: "personal" },
140
+ hqRoot,
141
+ stateDir,
142
+ installationId: "install-shard",
143
+ machineId: "machine-shard",
144
+ source: "cli",
145
+ sequence: 1,
146
+ hashPolicy: "never",
147
+ maxWallMs: 60_000,
148
+ persistSnapshot: false,
149
+ });
150
+ expect(new Set(opened.paths).size).toBe(1);
151
+ });
152
+ });
153
+ //# sourceMappingURL=ledger-shard-isolation.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ledger-shard-isolation.test.js","sourceRoot":"","sources":["../../src/manifest/ledger-shard-isolation.test.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,160 @@
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
+ * The serialised-byte budget the NEXT pass should plan chunks against.
93
+ *
94
+ * Absent means "use the contract default"
95
+ * (`SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET`), which is the state every
96
+ * healthy scope stays in forever. It is written only by the 413 self-heal:
97
+ * a scope whose entries are fat enough that the default budget still
98
+ * produced a body the server refused halves it here, so the reduction
99
+ * survives into the next pass instead of being re-discovered (and re-failed)
100
+ * every cycle.
101
+ *
102
+ * Additive and optional, validated leniently for the same reason
103
+ * {@link ManifestSnapshot.consecutiveFailures} is: an older build's snapshot
104
+ * has no such field and must read back as "use the default", not as
105
+ * corruption.
106
+ */
107
+ chunkByteBudget?: number;
108
+ }
109
+ /**
110
+ * Stable per-scope key. `personal` and `company:{uid}` are deliberately
111
+ * different namespaces: a personal snapshot must never be reused as the delta
112
+ * base for a company scope (that would emit every company file as "removed"
113
+ * from the personal vault, and vice versa) — a tenant-boundary bug, not just
114
+ * a correctness one.
115
+ */
116
+ export declare function manifestSnapshotScopeKey(scope: SyncManifestScope): string;
117
+ /**
118
+ * Filename-safe form of a scope key. Every character outside `[A-Za-z0-9_-]`
119
+ * collapses to `_`, so a hostile or merely surprising companyUid can never
120
+ * escape the snapshot directory via `../` or a separator.
121
+ *
122
+ * That collapse is MANY-TO-ONE, and the contract's identifier rule admits
123
+ * `.` and `:` inside a companyUid — so `company:acme.eu` and `company:acme:eu`
124
+ * would otherwise sanitize to the SAME file and two tenants would share one
125
+ * delta base. Sharing a base across companies is a tenant-boundary bug: the
126
+ * second scope's delta would emit every file of the first as `removedPaths`.
127
+ * A digest of the RAW key is therefore appended, which is injective in
128
+ * practice while keeping the readable prefix for humans grepping the dir.
129
+ *
130
+ * {@link manifestSnapshotScopeSlug} is the extension-less form, reused by the
131
+ * upload pass to name its per-scope lock file — the same injectivity argument
132
+ * applies there, and for the same tenant-boundary reason: two scopes must
133
+ * never share one lock any more than they may share one delta base.
134
+ */
135
+ export declare function manifestSnapshotScopeSlug(scopeKey: string): string;
136
+ export declare function manifestSnapshotFileName(scopeKey: string): string;
137
+ export declare function manifestSnapshotPath(stateDir: string, scopeKey: string): string;
138
+ /** Generate an id that satisfies the contract's opaque-identifier validator. */
139
+ export declare function newManifestSnapshotId(): string;
140
+ /**
141
+ * Read the snapshot for a scope, or `null` when there is nothing usable.
142
+ *
143
+ * "Nothing usable" covers absence, unreadable files, invalid JSON, and any
144
+ * structurally wrong payload. All four collapse to the same safe outcome — a
145
+ * full manifest — so the caller never has to branch on why.
146
+ */
147
+ export declare function readManifestSnapshot(stateDir: string, scopeKey: string): ManifestSnapshot | null;
148
+ /** True when this snapshot's entries may be used as a delta base. */
149
+ export declare function isManifestSnapshotBaseUsable(snapshot: ManifestSnapshot): boolean;
150
+ /**
151
+ * Persist a snapshot atomically. Returns `false` on any failure.
152
+ *
153
+ * A failed write is deliberately NOT an error for the caller: the manifest it
154
+ * just built is still valid and still uploadable; the only consequence is
155
+ * that the next cycle re-sends a full manifest.
156
+ */
157
+ export declare function writeManifestSnapshot(stateDir: string, scopeKey: string, snapshot: ManifestSnapshot): boolean;
158
+ /** True when the snapshot is too old to be trusted as a delta base. */
159
+ export declare function isManifestSnapshotStale(snapshot: ManifestSnapshot, nowMs: number, maxAgeMs?: number): boolean;
160
+ //# 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;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;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,CAyFhG;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,300 @@
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
+ // Untrusted JSON, same as the count above. A zero, negative, fractional or
188
+ // absurd budget degrades to absent ("use the default") rather than to a
189
+ // planner that cuts one chunk per entry — the conservative reading, since a
190
+ // too-LARGE budget is re-halved by the next 413 anyway.
191
+ if (typeof raw.chunkByteBudget === "number" &&
192
+ Number.isSafeInteger(raw.chunkByteBudget) &&
193
+ raw.chunkByteBudget > 0) {
194
+ snapshot.chunkByteBudget = raw.chunkByteBudget;
195
+ }
196
+ return snapshot;
197
+ }
198
+ /** True when this snapshot's entries may be used as a delta base. */
199
+ export function isManifestSnapshotBaseUsable(snapshot) {
200
+ return snapshot.baseValid !== false;
201
+ }
202
+ /**
203
+ * Persist a snapshot atomically. Returns `false` on any failure.
204
+ *
205
+ * A failed write is deliberately NOT an error for the caller: the manifest it
206
+ * just built is still valid and still uploadable; the only consequence is
207
+ * that the next cycle re-sends a full manifest.
208
+ */
209
+ export function writeManifestSnapshot(stateDir, scopeKey, snapshot) {
210
+ const target = manifestSnapshotPath(stateDir, scopeKey);
211
+ const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
212
+ try {
213
+ fs.mkdirSync(path.dirname(target), { recursive: true });
214
+ writeSnapshotIncrementally(tmp, snapshot);
215
+ fs.renameSync(tmp, target);
216
+ return true;
217
+ }
218
+ catch {
219
+ try {
220
+ fs.rmSync(tmp, { force: true });
221
+ }
222
+ catch {
223
+ // Best effort; a stray tmp file is harmless and is overwritten by the
224
+ // next attempt's pid/timestamp-unique name.
225
+ }
226
+ return false;
227
+ }
228
+ }
229
+ /** True when the snapshot is too old to be trusted as a delta base. */
230
+ export function isManifestSnapshotStale(snapshot, nowMs, maxAgeMs = MANIFEST_SNAPSHOT_MAX_AGE_MS) {
231
+ const generatedMs = Date.parse(snapshot.generatedAt);
232
+ if (!Number.isFinite(generatedMs))
233
+ return true;
234
+ // A snapshot stamped in the FUTURE (clock skew, restored backup) is treated
235
+ // as stale too — its age is unknowable, so re-baseline rather than trust it.
236
+ if (generatedMs > nowMs)
237
+ return true;
238
+ return nowMs - generatedMs > maxAgeMs;
239
+ }
240
+ /**
241
+ * Serialise the snapshot to `tmp` INCREMENTALLY, a bounded batch of entries at
242
+ * a time.
243
+ *
244
+ * `JSON.stringify(snapshot)` builds one string holding the entire record
245
+ * before a single byte reaches the disk. On a 199k-entry scope that string is
246
+ * tens of megabytes of transient allocation, arriving at the moment the pass
247
+ * is already at its peak (the entry list, the ledger index and the snapshot
248
+ * map are all still live), so it lands squarely on the number the memory
249
+ * budget is measured against.
250
+ *
251
+ * Streaming the same bytes costs one batch instead. The output is byte-for-byte
252
+ * the JSON `JSON.stringify` would have produced for this shape — the top-level
253
+ * scalars first, then `entries` written key by key — so `readManifestSnapshot`
254
+ * is unchanged and an older reader parses it identically.
255
+ */
256
+ function writeSnapshotIncrementally(tmp, snapshot) {
257
+ const { entries, ...header } = snapshot;
258
+ const fd = fs.openSync(tmp, "w");
259
+ try {
260
+ // Batched, not per-entry: one `writeSync` per entry on a 199k-entry scope
261
+ // is 199k syscalls, which trades the memory win for a wall-clock loss.
262
+ let buffer = "";
263
+ const flush = (force) => {
264
+ if (!force && buffer.length < SNAPSHOT_WRITE_BATCH_CHARS)
265
+ return;
266
+ if (buffer.length === 0)
267
+ return;
268
+ fs.writeSync(fd, buffer, null, "utf8");
269
+ buffer = "";
270
+ };
271
+ // `JSON.stringify` on the header alone: it is a handful of scalars, and
272
+ // hand-rolling their escaping would be a needless second encoder.
273
+ const headerJson = JSON.stringify(header);
274
+ // `{...}` → `{...,"entries":{` — the header is never empty (`snapshotId`,
275
+ // `generatedAt` and `sequence` are required), so the comma is always right.
276
+ buffer += `${headerJson.slice(0, -1)},"entries":{`;
277
+ let first = true;
278
+ for (const key in entries) {
279
+ const entry = entries[key];
280
+ if (entry === undefined)
281
+ continue;
282
+ buffer += first ? "" : ",";
283
+ first = false;
284
+ buffer += `${JSON.stringify(key)}:${JSON.stringify(entry)}`;
285
+ flush(false);
286
+ }
287
+ buffer += "}}\n";
288
+ flush(true);
289
+ // Durability parity with the previous `writeFileSync` + `renameSync`: the
290
+ // rename is only atomic with respect to content that has actually reached
291
+ // the file.
292
+ fs.fsyncSync(fd);
293
+ }
294
+ finally {
295
+ fs.closeSync(fd);
296
+ }
297
+ }
298
+ /** Flush threshold for the incremental snapshot writer (characters, not bytes). */
299
+ const SNAPSHOT_WRITE_BATCH_CHARS = 256 * 1024;
300
+ //# 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"}