@openparachute/vault 0.7.3-rc.10 → 0.7.3-rc.11

package/core/src/attachment/bytes-provider.ts

@@ -0,0 +1,65 @@
+/**
+ * `AttachmentBytesProvider` — the model-lane (Wave 2) byte-access seam.
+ * Mirrors `AttachmentTicketProvider` (`./tickets.ts`): a per-door
+ * implementation binds this to its own storage (bun: local fs, see
+ * `src/attachment-bytes.ts`; a future cloud implementation: ranged R2 GETs
+ * through the vault DO). Core stays storage-unaware — the `read-attachment`
+ * tool (`core/src/mcp.ts`) calls only through this interface, so bun and a
+ * future cloud implementation can never drift on the read contract.
+ *
+ * Deliberately narrow: stat + a bounded positional read, plus one optional
+ * hook for the audio transcript pointer. All POLICY (mime-family dispatch,
+ * size caps, range validation, tag-scope) lives in the `read-attachment`
+ * tool itself — same division as the ticket seam (`GenerateMcpToolsOpts`'s
+ * doc comment in `core/src/mcp.ts`).
+ *
+ * D10 (attachments-for-agents design): "tools omitted when unwired" — a
+ * door that hasn't wired this seam simply never passes `attachmentBytes` to
+ * `generateMcpTools`, so `read-attachment` is absent from `tools/list`
+ * entirely, not merely erroring on call.
+ */
+
+import type { Attachment } from "../types.js";
+
+/**
+ * 4 MiB raw-bytes cap on the image branch of `read-attachment` (D3): the
+ * largest honest budget under Claude's ~5 MB image API limit, with room for
+ * base64 blow-up (~5.6 MiB on the wire) and DO-transient headroom on a
+ * future cloud implementation. Enforced BEFORE a read is attempted — the
+ * tool calls `stat()` first and refuses over-cap without ever calling
+ * `readRange()`.
+ */
+export const MAX_ATTACHMENT_IMAGE_BYTES = 4 * 1024 * 1024;
+
+export interface AttachmentBytesProvider {
+  /**
+   * Byte size of the attachment's stored bytes, or `null` when the row
+   * exists but its bytes don't — e.g. an `audio_retention` eviction after a
+   * successful transcription (`src/transcription-worker.ts` unlinks the
+   * file on `until_transcribed` / `never` retention), or any other
+   * out-of-band loss. Drives the `attachment_binary_missing` refusal.
+   */
+  stat(attachment: Attachment): Promise<{ size: number } | null>;
+  /**
+   * Read the half-open byte range `[start, end)`. Bounded by construction —
+   * callers never ask for the whole file when only a window is needed (the
+   * text path); the image path DOES read start-to-end, but only after
+   * `stat()` has already confirmed the file is under
+   * {@link MAX_ATTACHMENT_IMAGE_BYTES}. `start`/`end` are always within
+   * `[0, size]` as reported by a prior `stat()` call on the same attachment
+   * — implementations don't need to re-clamp defensively, though doing so
+   * costs nothing.
+   */
+  readRange(attachment: Attachment, start: number, end: number): Promise<Uint8Array>;
+  /**
+   * OPTIONAL: resolve the sibling transcript note for a completed
+   * audio/video transcription (bun: `<attachment-path>.transcript`, see
+   * `transcriptPathFor` in `src/transcript-note.ts`). Omitted by a door
+   * whose transcript instead lives in the owning note's body (the design's
+   * cloud path, D... — no separate sibling note to point at) — the
+   * `read-attachment` audio branch falls back to `note_id` alone (the
+   * owning note) in that case, per the design's "on cloud the transcript
+   * lives in the owning note's body, so `note_id` is the pointer."
+   */
+  resolveTranscriptNote?(attachment: Attachment): Promise<{ id: string; path: string } | null>;
+}

package/core/src/content-range.test.ts

@@ -23,8 +23,13 @@ import {
   parseContentRange,
   sliceContentRange,
   applyContentRange,
+  parseAttachmentContentRange,
+  alignByteWindow,
   MIN_CONTENT_LENGTH,
+  DEFAULT_ATTACHMENT_WINDOW_BYTES,
+  MAX_ATTACHMENT_WINDOW_BYTES,
 } from "./content-range.js";
+import { QueryError } from "./query-operators.js";
 
 // ---------------------------------------------------------------------------
 // 1. parseContentRange
@@ -237,6 +242,128 @@ describe("content range — reassembly property", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// 2c. parseAttachmentContentRange + alignByteWindow (read-attachment)
+// ---------------------------------------------------------------------------
+
+describe("parseAttachmentContentRange", () => {
+  it("defaults offset=0, length=DEFAULT_ATTACHMENT_WINDOW_BYTES when both are omitted", () => {
+    expect(parseAttachmentContentRange(undefined, undefined)).toEqual({
+      offset: 0,
+      length: DEFAULT_ATTACHMENT_WINDOW_BYTES,
+    });
+  });
+
+  it("offset only → length still defaults (never 'read to end' — that's the query-notes shape, not this one)", () => {
+    expect(parseAttachmentContentRange(1000, undefined)).toEqual({
+      offset: 1000,
+      length: DEFAULT_ATTACHMENT_WINDOW_BYTES,
+    });
+  });
+
+  it("accepts an explicit length up to the max", () => {
+    expect(parseAttachmentContentRange(0, MAX_ATTACHMENT_WINDOW_BYTES)).toEqual({
+      offset: 0,
+      length: MAX_ATTACHMENT_WINDOW_BYTES,
+    });
+  });
+
+  it("rejects a length below MIN_CONTENT_LENGTH", () => {
+    expect(() => parseAttachmentContentRange(0, 2)).toThrow(QueryError);
+  });
+
+  it("rejects a length above MAX_ATTACHMENT_WINDOW_BYTES", () => {
+    expect(() => parseAttachmentContentRange(0, MAX_ATTACHMENT_WINDOW_BYTES + 1)).toThrow(QueryError);
+  });
+
+  it("rejects a negative offset", () => {
+    expect(() => parseAttachmentContentRange(-1, undefined)).toThrow(QueryError);
+  });
+});
+
+describe("alignByteWindow", () => {
+  /**
+   * Simulates the real caller: a BOUNDED positional read of
+   * `[max(0, offset-3), min(total, offset+length))` from `full`, THEN
+   * alignment — never handing the whole buffer to `alignByteWindow`, so a
+   * pass here proves the "never load the whole file" contract actually
+   * holds and isn't just true by accident of the test passing the full
+   * buffer.
+   */
+  function boundedRead(full: Buffer, offset: number, length: number): { raw: Uint8Array; rawStart: number } {
+    const total = full.byteLength;
+    const rawStart = Math.max(0, offset - 3);
+    // +1: alignByteWindow's end-boundary check reads the byte AT the
+    // (exclusive) window end to decide whether it's a continuation byte —
+    // that's one byte past `offset + length`, so the read must include it
+    // (see alignByteWindow's doc comment precondition).
+    const rawEnd = Math.min(total, offset + length + 1);
+    return { raw: full.subarray(rawStart, Math.max(rawStart, rawEnd)), rawStart };
+  }
+
+  it("offset past end → empty slice, complete (mirrors sliceContentRange)", () => {
+    const full = Buffer.from("abc", "utf8");
+    const { raw, rawStart } = boundedRead(full, 999, 16);
+    const r = alignByteWindow(raw, rawStart, { offset: 999, length: 16 }, full.byteLength);
+    expect(r.content).toBe("");
+    expect(r.content_offset).toBe(3);
+    expect(r.content_total_length).toBe(3);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("matches sliceContentRange byte-for-byte on a plain ASCII window", () => {
+    const s = "hello world";
+    const full = Buffer.from(s, "utf8");
+    const { raw, rawStart } = boundedRead(full, 0, 5);
+    const bounded = alignByteWindow(raw, rawStart, { offset: 0, length: 5 }, full.byteLength);
+    const whole = sliceContentRange(s, { offset: 0, length: 5 });
+    expect(bounded).toEqual(whole);
+  });
+
+  it("never splits a codepoint under a bounded read (matches sliceContentRange across a 4-byte emoji)", () => {
+    const s = "ab\u{1F600}cd"; // emoji occupies bytes 2..5 of 8
+    const full = Buffer.from(s, "utf8");
+    for (const [offset, length] of [
+      [0, 5], // budget cuts mid-emoji → backs off to byte 2
+      [2, 4], // exact emoji window
+      [4, 8], // offset lands mid-emoji → aligns down to byte 2
+      [6, 4], // final ASCII tail
+    ] as const) {
+      const { raw, rawStart } = boundedRead(full, offset, length);
+      const bounded = alignByteWindow(raw, rawStart, { offset, length }, full.byteLength);
+      const whole = sliceContentRange(s, { offset, length });
+      expect(bounded).toEqual(whole);
+    }
+  });
+
+  it("reassembly property: chaining content_next_offset through BOUNDED reads reproduces the full content", () => {
+    const rand = mulberry32(0xba5eba11);
+    const POOL = ["a", "Z", "9", " ", "\n", "é", "ψ", "你", "‱", "\u{1F600}", "\u{1D11E}"];
+    for (let iter = 0; iter < 40; iter++) {
+      const charCount = Math.floor(rand() * 100);
+      let content = "";
+      for (let i = 0; i < charCount; i++) content += POOL[Math.floor(rand() * POOL.length)]!;
+      const full = Buffer.from(content, "utf8");
+      const total = full.byteLength;
+      const budget = MIN_CONTENT_LENGTH + Math.floor(rand() * 13); // 4..16 bytes
+
+      let offset = 0;
+      let assembled = "";
+      for (let step = 0; step <= total + 2; step++) {
+        const { raw, rawStart } = boundedRead(full, offset, budget);
+        const slice = alignByteWindow(raw, rawStart, { offset, length: budget }, total);
+        expect(Buffer.byteLength(slice.content, "utf8")).toBeLessThanOrEqual(budget);
+        expect(slice.content_total_length).toBe(total);
+        assembled += slice.content;
+        if (slice.content_next_offset === null) break;
+        expect(slice.content_next_offset).toBeGreaterThan(offset);
+        offset = slice.content_next_offset;
+      }
+      expect(assembled).toBe(content);
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // 3. MCP face — query-notes
 // ---------------------------------------------------------------------------

package/core/src/content-range.ts

@@ -183,3 +183,103 @@ export function applyContentRange(
   result.content_total_length = fields.content_total_length;
   result.content_next_offset = fields.content_next_offset;
 }
+
+// ---------------------------------------------------------------------------
+// Attachment byte-window reads (`read-attachment`, Wave 2 model lane)
+// ---------------------------------------------------------------------------
+
+/** Default `read-attachment` text window when the caller omits `content_length` — small enough to never nuke a context budget. */
+export const DEFAULT_ATTACHMENT_WINDOW_BYTES = 65_536; // 64 KiB
+
+/** Hard per-call ceiling on `read-attachment`'s `content_length` — a deliberate-big-bite max, not a default. */
+export const MAX_ATTACHMENT_WINDOW_BYTES = 262_144; // 256 KiB
+
+/**
+ * Parse `read-attachment`'s `content_offset` / `content_length` pair.
+ * Unlike {@link parseContentRange} (query-notes: omitted params mean "range
+ * mode off, return everything"), a `read-attachment` call ALWAYS reads a
+ * bounded window — omitting `content_length` defaults it to
+ * {@link DEFAULT_ATTACHMENT_WINDOW_BYTES} rather than "the whole file" (an
+ * attachment can be arbitrarily large; a note can't cheaply be). Returns a
+ * fully-resolved `{offset, length}` (never the query-notes "null = off"
+ * shape). Throws `QueryError` (INVALID_QUERY) on a negative/non-integer
+ * value, a `content_length` below {@link MIN_CONTENT_LENGTH}, or one above
+ * {@link MAX_ATTACHMENT_WINDOW_BYTES}.
+ */
+export function parseAttachmentContentRange(
+  offsetRaw: unknown,
+  lengthRaw: unknown,
+): { offset: number; length: number } {
+  const offset = toNonNegativeInt(offsetRaw, "content_offset") ?? 0;
+  const length = toNonNegativeInt(lengthRaw, "content_length");
+  if (length !== undefined && length < MIN_CONTENT_LENGTH) {
+    throw new QueryError(
+      `invalid \`content_length\` value ${JSON.stringify(lengthRaw)} — must be at least ${MIN_CONTENT_LENGTH} bytes (the size of the largest UTF-8 codepoint, so every window makes progress).`,
+      "INVALID_QUERY",
+    );
+  }
+  if (length !== undefined && length > MAX_ATTACHMENT_WINDOW_BYTES) {
+    throw new QueryError(
+      `invalid \`content_length\` value ${JSON.stringify(lengthRaw)} — exceeds the ${MAX_ATTACHMENT_WINDOW_BYTES} byte (256 KiB) per-call max for read-attachment.`,
+      "INVALID_QUERY",
+    );
+  }
+  return { offset, length: length ?? DEFAULT_ATTACHMENT_WINDOW_BYTES };
+}
+
+/**
+ * Byte-level counterpart to {@link sliceContentRange} for `read-attachment`'s
+ * text path, where loading the WHOLE file into memory to slice a string
+ * (`sliceContentRange`'s approach) is exactly the thing a 500 MB attachment
+ * forbids. The caller does a BOUNDED positional read first — `raw` is
+ * whatever bytes it actually fetched, starting at file offset `rawStart`
+ * — and this function applies the identical alignment rules
+ * `sliceContentRange` applies to a full in-memory string, operating only on
+ * that window.
+ *
+ * Precondition (caller's responsibility, not re-validated here): `raw`
+ * covers at least `[max(0, range.offset - 3), min(total, range.offset +
+ * range.length) + 1)` — i.e. from 3 bytes before the requested offset
+ * through ONE byte past the requested end, clamped to `total`. The 3-byte
+ * lookback is enough to find the leading byte of any UTF-8 codepoint the
+ * requested `offset` might land inside (a codepoint is at most 4 bytes,
+ * i.e. at most 3 continuation bytes after its leading byte); the 1-byte
+ * lookahead is what the end-alignment check reads to decide whether the
+ * budget cut lands mid-codepoint (mirroring `sliceContentRange`, which
+ * checks `bytes[end]` — the byte AT the exclusive cut point).
+ */
+export function alignByteWindow(
+  raw: Uint8Array,
+  rawStart: number,
+  range: { offset: number; length: number },
+  total: number,
+): ContentRangeFields {
+  if (range.offset >= total) {
+    return {
+      content: "",
+      content_offset: total,
+      content_total_length: total,
+      content_next_offset: null,
+    };
+  }
+
+  const byteAt = (idx: number): number => raw[idx - rawStart]!;
+
+  // Align the start DOWN to the leading byte of the codepoint containing
+  // `offset` — same rule as sliceContentRange, bounded to what's in `raw`.
+  let start = range.offset;
+  while (start > rawStart && isContinuationByte(byteAt(start))) start--;
+
+  // Window end: budget capped at total, then clamped to what's actually in
+  // `raw` (defense-in-depth — a caller that under-read would otherwise
+  // index past the buffer). Aligned DOWN so the slice never ends mid-codepoint.
+  let end = Math.min(start + range.length, total, rawStart + raw.length);
+  while (end > start && end < total && isContinuationByte(byteAt(end))) end--;
+
+  return {
+    content: Buffer.from(raw.subarray(start - rawStart, end - rawStart)).toString("utf8"),
+    content_offset: start,
+    content_total_length: total,
+    content_next_offset: end >= total ? null : end,
+  };
+}