@indigoai-us/hq-cloud 6.14.46 → 6.14.48

package/src/journal.test.ts

@@ -16,6 +16,7 @@ import {
   readJournal,
   writeJournal,
   updateEntry,
+  PrematureJournalEntryError,
   migrateToV2,
   normalizeJournalKeys,
   appendPullRecord,
@@ -208,12 +209,54 @@ describe("journal", () => {
   describe("updateEntry", () => {
     it("stamps lastSync and the per-file syncedAt", () => {
       const j: SyncJournal = { version: "1", lastSync: "", files: {} };
-      updateEntry(j, "foo.md", "hash", 10, "up");
+      const abs = path.join(stateDir, "foo.md");
+      fs.writeFileSync(abs, "x");
+      updateEntry(j, "foo.md", "hash", 10, "up", abs);
       expect(j.files["foo.md"]?.hash).toBe("hash");
       expect(j.files["foo.md"]?.direction).toBe("up");
       expect(j.lastSync).not.toBe("");
       expect(j.files["foo.md"]?.syncedAt).not.toBe("");
     });
+
+    // Load-bearing once delete propagation authorizes on ETag currency alone:
+    // an entry whose file was never written is indistinguishable from "the
+    // user deleted this", and the next push would issue a remote DeleteObject
+    // for what was only premature bookkeeping.
+    it("refuses to journal a path that is not on disk", () => {
+      const j: SyncJournal = { version: "1", lastSync: "", files: {} };
+      const missing = path.join(stateDir, "never-written.md");
+      expect(() => updateEntry(j, "never-written.md", "hash", 10, "down", missing)).toThrow(
+        PrematureJournalEntryError,
+      );
+      expect(j.files).not.toHaveProperty("never-written.md");
+      expect(j.lastSync).toBe("");
+    });
+
+    it("accepts a dangling symlink — the link itself is the synced object", () => {
+      const j: SyncJournal = { version: "1", lastSync: "", files: {} };
+      const link = path.join(stateDir, "dangling-link");
+      fs.symlinkSync(path.join(stateDir, "no-such-target"), link);
+      expect(() =>
+        updateEntry(j, "dangling-link", "hash", 0, "down", link, { kind: "symlink" }),
+      ).not.toThrow();
+      expect(j.files["dangling-link"]?.kind).toBe("symlink");
+    });
+
+    // Regression: `kind` and `createdBySub` were adjacent trailing optionals
+    // and two call sites passed kind into the createdBySub slot, leaving
+    // entry.kind unset. entry.kind gates delete-intent minting, so those
+    // entries could never be deleted. Named options make it unrepresentable.
+    it("records kind and createdBySub into their own fields", () => {
+      const j: SyncJournal = { version: "1", lastSync: "", files: {} };
+      const abs = path.join(stateDir, "typed.md");
+      fs.writeFileSync(abs, "x");
+      updateEntry(j, "typed.md", "hash", 1, "down", abs, {
+        kind: "file",
+        createdBySub: "sub-123",
+      });
+      expect(j.files["typed.md"]?.kind).toBe("file");
+      expect(j.files["typed.md"]?.createdBySub).toBe("sub-123");
+    });
   });
 
   // ── Journal v2 (US-005): pulls, tombstones, GC, migration ─────────────────

package/src/journal.ts

@@ -416,17 +416,82 @@ export function hashSymlinkTarget(target: string): string {
  * via `hq files get` are pulled — `direction:"down"` — but ride the pin union
  * in the caller's inclusion prefixSet, so they are likewise never pruned.)
  */
+/**
+ * Thrown when a caller tries to journal a path that is not on disk.
+ *
+ * Deliberately loud rather than a silent skip: a caller reaching this has a
+ * real ordering bug, and swallowing it would reintroduce exactly the silent
+ * drift this guard exists to prevent.
+ */
+export class PrematureJournalEntryError extends Error {
+  constructor(readonly relativePath: string, readonly absolutePath: string) {
+    super(
+      `refusing to journal '${relativePath}': no file at '${absolutePath}'. ` +
+        `A journal entry must be written only AFTER its file is on disk.`,
+    );
+    this.name = "PrematureJournalEntryError";
+  }
+}
+
+/**
+ * Optional fields of a journal entry.
+ *
+ * These are an OBJECT rather than trailing positional parameters because they
+ * were four adjacent optionals, two of them `string`, and callers drifted:
+ * two conflict-resolution sites in `cli/sync.ts` passed their `"file" |
+ * "symlink"` value into the `createdBySub` slot, so `entry.kind` was silently
+ * never set on any conflict-resolved entry. That is not cosmetic — `entry.kind`
+ * gates delete-intent minting (`markLocalDeleteIntent` requires it to match,
+ * and the watcher skips any entry without one), so a file that had ever been
+ * through conflict resolution could never be deleted, even with a live watcher.
+ * Named fields make that class of mistake unrepresentable.
+ */
+export interface UpdateEntryOptions {
+  remoteEtag?: string;
+  mtimeMs?: number;
+  /** Object's `created-by-sub` S3 metadata. Download path only. */
+  createdBySub?: string;
+  kind?: "file" | "symlink";
+}
+
+/**
+ * Record a journal entry for a file that is CONFIRMED present on disk.
+ *
+ * `verifyAbsolutePath` is required, and the entry is written only after an
+ * `lstat` proves the file exists. This is a load-bearing invariant, not a
+ * defensive nicety: a journal entry says "this key was synced and the local
+ * copy is at this hash". Once delete propagation authorizes on ETag currency
+ * alone (no watcher-minted intent), an entry whose file was never actually
+ * written becomes indistinguishable from "the user deleted this file" — and
+ * the next push issues a remote DeleteObject for a file that was only ever
+ * premature bookkeeping.
+ *
+ * Every existing caller already had a `fs.lstatSync` in hand and passed values
+ * derived from it, so this makes an existing convention structural. The point
+ * is that a FUTURE caller cannot get it wrong: with the check inside this
+ * function there is no longer a way to add a call site that records an entry
+ * for a file that is not there.
+ *
+ * `lstat` (not `stat`) so a dangling symlink still counts as present — the
+ * link itself is the synced object, and its target may legitimately be absent.
+ *
+ * @throws PrematureJournalEntryError when nothing exists at `verifyAbsolutePath`.
+ */
 export function updateEntry(
   journal: SyncJournal,
   relativePath: string,
   hash: string,
   size: number,
   direction: "up" | "down",
-  remoteEtag?: string,
-  mtimeMs?: number,
-  createdBySub?: string,
-  kind?: "file" | "symlink",
+  verifyAbsolutePath: string,
+  opts: UpdateEntryOptions = {},
 ): void {
+  try {
+    fs.lstatSync(verifyAbsolutePath);
+  } catch {
+    throw new PrematureJournalEntryError(relativePath, verifyAbsolutePath);
+  }
+  const { remoteEtag, mtimeMs, createdBySub, kind } = opts;
   const entry: JournalEntry = {
     hash,
     size,

package/src/s3.test.ts

@@ -1679,6 +1679,12 @@ describe("validateVaultUploadKey — direct-S3 key poisoning guard (incident 202
     ["a/../b.md", "INVALID_KEY_DOT_COMPONENT"],
     ["a/./b.md", "INVALID_KEY_DOT_COMPONENT"],
     ["bad\x00key.md", "INVALID_KEY_CONTROL_CHARS"],
+    // macOS Finder custom-icon file. Named explicitly because this is the
+    // spelling that reaches the validator in the wild: Finder writes one into
+    // every directory it renders a custom icon for, and the push walker now
+    // excludes them precisely because this throw is unavoidable.
+    ["Icon\r", "INVALID_KEY_CONTROL_CHARS"],
+    ["docs/Icon\r", "INVALID_KEY_CONTROL_CHARS"],
   ])(
     "validateVaultUploadKey mirrors the server rule set: %j → %s",
     (key, code) => {