@dreamlake/dreamlake-cli 0.102.0 → 0.102.2

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.
@@ -9,6 +9,20 @@ export interface NotePresenceRoster {
9
9
  participants: Participant[];
10
10
  observedAt: number;
11
11
  }
12
+ export interface NoteContributorsPage {
13
+ sessions: {
14
+ id: string;
15
+ name: string;
16
+ namespaceSlug: string;
17
+ contribution: {
18
+ kind: 'created' | 'edited';
19
+ firstAt: string;
20
+ lastAt: string;
21
+ } | null;
22
+ }[];
23
+ hasMore: boolean;
24
+ nextCursor: string | null;
25
+ }
12
26
  export interface NotePresenceReceipt {
13
27
  state?: {
14
28
  user?: Participant['user'];
@@ -63,6 +77,10 @@ export declare function notePresenceIntent(value: string | undefined): {
63
77
  summary: string;
64
78
  } | undefined;
65
79
  export declare function notePresenceApi(t: Transport, base: string): {
80
+ contributors: (id: string, options?: {
81
+ cursor?: string;
82
+ pageSize?: number;
83
+ }) => Promise<NoteContributorsPage>;
66
84
  /** No join or heartbeat. The optional input retains the former POST API for compatibility. */
67
85
  presence: {
68
86
  (id: string): Promise<NotePresenceRoster>;
@@ -17,6 +17,7 @@ export function notePresenceApi(t, base) {
17
17
  ? t.request('GET', path(id) + '/presence', { query: { format: 'json' } })
18
18
  : updatePresence(id, input);
19
19
  return {
20
+ contributors: (id, options = {}) => t.request('GET', path(id) + '/contributors', { query: options }),
20
21
  /** No join or heartbeat. The optional input retains the former POST API for compatibility. */
21
22
  presence: presence,
22
23
  presenceText: async (id) => {
@@ -306,6 +306,10 @@ export declare function notesApi(t: Transport, namespace: string): {
306
306
  after?: string;
307
307
  }, ifMatch?: string) => Promise<WriteReceipt>;
308
308
  removeSection: (noteId: string, anchor: string, ifMatch?: string) => Promise<WriteReceipt>;
309
+ contributors: (id: string, options?: {
310
+ cursor?: string;
311
+ pageSize?: number;
312
+ }) => Promise<import("./note-presence.js").NoteContributorsPage>;
309
313
  presence: {
310
314
  (id: string): Promise<import("./note-presence.js").NotePresenceRoster>;
311
315
  (id: string, input: Record<string, unknown>): Promise<import("./note-presence.js").NotePresenceReceipt>;
@@ -9,13 +9,19 @@ export function noteAgentHeaders(path, env = process.env) {
9
9
  }
10
10
  /** Send conversation context only to supported DreamLake resource routes. */
11
11
  export function resourceSessionHeaders(path, env = process.env) {
12
- if (!/^\/(?:namespaces\/[^/]+\/(?:notes|repos)\/[^/?]+(?:[/?]|$)|infrastructure\/stacks\/[^/?]+(?:[/?]|$)|resources\/)/.test(path))
12
+ if (!/^\/(?:namespaces\/[^/]+\/(?:notes|repos)(?:[/?]|$)|infrastructure\/stacks\/[^/?]+(?:[/?]|$)|resources\/)/.test(path))
13
13
  return {};
14
- const id = env.DREAMLAKE_SESSION_ID || env.CODEX_THREAD_ID;
15
- const provider = env.DREAMLAKE_SESSION_PROVIDER || (env.CODEX_THREAD_ID && !env.DREAMLAKE_SESSION_ID ? 'codex' : undefined);
14
+ const preference = env.DREAMLAKE_SESSION_AFFILIATION === '0' ? { 'X-DreamLake-Session-Affiliation': '0' } : {};
15
+ const saved = env.DREAMLAKE_TERMINAL_SESSION_ID;
16
+ if (saved)
17
+ return /^[a-f0-9]{24}$/.test(saved) ? { ...preference, 'X-DreamLake-Terminal-Session-Id': saved } : preference;
18
+ const claude = env.CLAUDE_SESSION_ID || env.CLAUDE_CODE_SESSION_ID;
19
+ const native = env.CODEX_THREAD_ID && claude ? undefined : env.CODEX_THREAD_ID || claude;
20
+ const id = env.DREAMLAKE_SESSION_ID || native;
21
+ const provider = env.DREAMLAKE_SESSION_PROVIDER || (!env.DREAMLAKE_SESSION_ID && native ? env.CODEX_THREAD_ID ? 'codex' : 'claude' : undefined);
16
22
  if (!id || id.length > 128 || /[^\x20-\x7e]/.test(id) || !provider || !['codex', 'claude', 'agent'].includes(provider))
17
- return {};
23
+ return preference;
18
24
  const name = env.DREAMLAKE_SESSION_NAME;
19
- return { 'X-DreamLake-Session-Id': id, 'X-DreamLake-Session-Provider': provider,
25
+ return { ...preference, 'X-DreamLake-Session-Id': id, 'X-DreamLake-Session-Provider': provider,
20
26
  ...(name && name.length <= 256 && !/[^\x20-\x7e]/.test(name) ? { 'X-DreamLake-Session-Name': name } : {}) };
21
27
  }
@@ -1,6 +1,8 @@
1
1
  import type { DreamdbBackend } from "../compat/s3-backend.js";
2
2
  export declare const MAGIC = "DREAMLAKE-ARTIFACT-CHUNKS/1\n";
3
3
  export declare const MAX_SIZE: number;
4
+ export declare const MAX_MANIFEST_SIZE: number;
5
+ export declare const MAX_CHUNK: number;
4
6
  export interface Chunk {
5
7
  sha256: string;
6
8
  size: number;
@@ -10,12 +12,15 @@ export interface Manifest {
10
12
  sha256: string;
11
13
  chunks: Chunk[];
12
14
  }
15
+ /** An optional optimization hint, never proof that its objects still exist. */
16
+ export declare function parseManifest(bytes?: Uint8Array | null): Manifest | null;
13
17
  /** Content-defined boundaries resynchronize after insertions/deletions. */
14
18
  export declare function splitChunks(bytes: Uint8Array): Uint8Array[];
15
19
  /** Chunks finish before the caller publishes the manifest through DreamDB CAS. */
16
- export declare function uploadIncremental(content: Uint8Array, backend: DreamdbBackend): Promise<{
20
+ export declare function uploadIncremental(content: Uint8Array, backend: DreamdbBackend, previousContent?: Uint8Array | null): Promise<{
17
21
  content: NodeJS.NonSharedUint8Array;
18
22
  uploadedBytes: number;
19
23
  uploadedChunks: number;
20
24
  reusedBytes: number;
25
+ reusedManifest: boolean;
21
26
  }>;
@@ -4,8 +4,9 @@ import { promisify } from "node:util";
4
4
  // Wire contract: UI docs/dev-notes/2026-09-30-artifact-incremental.md.
5
5
  export const MAGIC = "DREAMLAKE-ARTIFACT-CHUNKS/1\n";
6
6
  export const MAX_SIZE = 512 * 1024 * 1024;
7
+ export const MAX_MANIFEST_SIZE = 1024 * 1024;
7
8
  const MIN_CHUNK = 64 * 1024;
8
- const MAX_CHUNK = 1024 * 1024;
9
+ export const MAX_CHUNK = 1024 * 1024;
9
10
  const compress = promisify(gzip);
10
11
  const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
11
12
  let seed = 0x12345678;
@@ -15,6 +16,55 @@ const gear = Uint32Array.from({ length: 256 }, () => {
15
16
  seed ^= seed << 5;
16
17
  return seed >>> 0;
17
18
  });
19
+ /** An optional optimization hint, never proof that its objects still exist. */
20
+ export function parseManifest(bytes) {
21
+ if (!bytes || bytes.length > MAX_MANIFEST_SIZE)
22
+ return null;
23
+ const text = new TextDecoder().decode(bytes);
24
+ if (!text.startsWith(MAGIC))
25
+ return null;
26
+ try {
27
+ const value = JSON.parse(text.slice(MAGIC.length));
28
+ const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
29
+ if (!value || !Number.isSafeInteger(value.size) || value.size < 0 || value.size > MAX_SIZE ||
30
+ !hash(value.sha256) || !Array.isArray(value.chunks) || value.chunks.length > 8192)
31
+ return null;
32
+ let total = 0;
33
+ const sizes = new Map();
34
+ const chunks = [];
35
+ for (const chunk of value.chunks) {
36
+ if (!chunk || !hash(chunk.sha256) || !Number.isSafeInteger(chunk.size) ||
37
+ chunk.size <= 0 || chunk.size > MAX_CHUNK ||
38
+ (sizes.has(chunk.sha256) && sizes.get(chunk.sha256) !== chunk.size))
39
+ return null;
40
+ total += chunk.size;
41
+ if (total > value.size)
42
+ return null;
43
+ sizes.set(chunk.sha256, chunk.size);
44
+ chunks.push({ sha256: chunk.sha256, size: chunk.size });
45
+ }
46
+ return total === value.size ? { size: value.size, sha256: value.sha256, chunks } : null;
47
+ }
48
+ catch {
49
+ return null;
50
+ }
51
+ }
52
+ /** Verify the prior boundaries against the local bytes, without CDC scanning.
53
+ * A forged/corrupt envelope with a matching whole-file hash must not be reused. */
54
+ function unchangedParts(content, hash, previous) {
55
+ if (!previous || previous.size !== content.length || previous.sha256 !== hash)
56
+ return null;
57
+ const parts = [];
58
+ let offset = 0;
59
+ for (const chunk of previous.chunks) {
60
+ const part = content.subarray(offset, offset + chunk.size);
61
+ if (sha256(part) !== chunk.sha256)
62
+ return null;
63
+ parts.push(part);
64
+ offset += chunk.size;
65
+ }
66
+ return parts;
67
+ }
18
68
  /** Content-defined boundaries resynchronize after insertions/deletions. */
19
69
  export function splitChunks(bytes) {
20
70
  if (bytes.length > MAX_SIZE)
@@ -35,16 +85,27 @@ export function splitChunks(bytes) {
35
85
  return result;
36
86
  }
37
87
  /** Chunks finish before the caller publishes the manifest through DreamDB CAS. */
38
- export async function uploadIncremental(content, backend) {
39
- const parts = splitChunks(content);
40
- const manifest = { size: content.length, sha256: sha256(content), chunks: [] };
88
+ export async function uploadIncremental(content, backend, previousContent) {
89
+ if (content.length > MAX_SIZE)
90
+ throw new Error("incremental artifacts are limited to 512 MiB");
91
+ const contentHash = sha256(content);
92
+ const previous = parseManifest(previousContent);
93
+ const unchanged = unchangedParts(content, contentHash, previous);
94
+ const parts = unchanged ?? splitChunks(content);
95
+ const manifest = { size: content.length, sha256: contentHash, chunks: [] };
41
96
  const unique = new Map();
42
- for (const part of parts) {
43
- const hash = sha256(part);
97
+ for (const [index, part] of parts.entries()) {
98
+ const hash = unchanged ? previous.chunks[index].sha256 : sha256(part);
44
99
  manifest.chunks.push({ sha256: hash, size: part.length });
45
100
  unique.set(hash, part);
46
101
  }
47
102
  const entries = [...unique];
103
+ // One bounded batched storage query when supported. Older/custom backends
104
+ // retain their per-object HEAD path. A prior manifest is not existence proof:
105
+ // a missing object is repaired from the local bytes before publication.
106
+ const existing = backend.hasMany && entries.length
107
+ ? await backend.hasMany(entries.map(([hash]) => `artifact-chunks/v1/${hash}.gz`))
108
+ : null;
48
109
  let next = 0, uploadedBytes = 0, uploadedSourceBytes = 0, uploadedChunks = 0;
49
110
  let failure;
50
111
  const workers = Array.from({ length: Math.min(8, entries.length) }, async () => {
@@ -52,7 +113,7 @@ export async function uploadIncremental(content, backend) {
52
113
  const [hash, part] = entries[next++];
53
114
  try {
54
115
  const key = `artifact-chunks/v1/${hash}.gz`;
55
- if ((await backend.head(key)).exists)
116
+ if (existing ? existing.has(key) : (await backend.head(key)).exists)
56
117
  continue;
57
118
  const compressed = await compress(part);
58
119
  const result = await backend.put(key, compressed, { ifNoneMatchStar: true });
@@ -76,5 +137,6 @@ export async function uploadIncremental(content, backend) {
76
137
  content: new TextEncoder().encode(MAGIC + JSON.stringify(manifest)),
77
138
  uploadedBytes, uploadedChunks,
78
139
  reusedBytes: content.length - uploadedSourceBytes,
140
+ reusedManifest: unchanged !== null,
79
141
  };
80
142
  }
@@ -9,7 +9,7 @@ import { registerShareCommands } from "../share.js";
9
9
  // never transits the API server. See compat/dreamdb.ts.
10
10
  import { readFileSync, statSync } from "node:fs";
11
11
  import path from "node:path";
12
- import { uploadIncremental, MAX_SIZE } from "./incremental.js";
12
+ import { uploadIncremental, MAX_SIZE, MAX_MANIFEST_SIZE } from "./incremental.js";
13
13
  import { packPages } from "./pages.js";
14
14
  import { collectSite, uploadSite } from "./site.js";
15
15
  import { metaError, putArtifactCover, readCoverFile, registerArtifactMetaCommand } from "./meta.js";
@@ -197,8 +197,18 @@ export async function runDreamlakeArtifactPush(args, deps = {}) {
197
197
  const io = deps.dreamdb ?? realDreamdbIO;
198
198
  // 2) write the version straight to S3 via DreamDB.
199
199
  let version;
200
+ let previousContent = null;
200
201
  try {
201
- version = await io.nextVersion(broker.backendUrl, refName, backend, "artifact_id", artifactId);
202
+ // Avoid extra index/blob reads on small/medium inputs, where CDC is cheap.
203
+ // This is only an optimization threshold, not an upload size limit.
204
+ if (incremental && !site && content.length >= 64 * 1024 * 1024 && io.readHead) {
205
+ const head = await io.readHead(broker.backendUrl, refName, backend, "artifact_id", artifactId, MAX_MANIFEST_SIZE);
206
+ version = head.nextVersion;
207
+ previousContent = head.content;
208
+ }
209
+ else {
210
+ version = await io.nextVersion(broker.backendUrl, refName, backend, "artifact_id", artifactId);
211
+ }
202
212
  }
203
213
  catch (e) {
204
214
  // Abort BEFORE writing — never guess v1 on a read failure and clobber
@@ -217,7 +227,7 @@ export async function runDreamlakeArtifactPush(args, deps = {}) {
217
227
  process.stdout.write(` site: ${site.manifest.files.length} files, ${result.uploadedFiles} new files, ${result.uploadedBytes} bytes uploaded\n`);
218
228
  }
219
229
  else if (incremental) {
220
- const result = await uploadIncremental(content, backend);
230
+ const result = await uploadIncremental(content, backend, previousContent);
221
231
  storedContent = result.content;
222
232
  process.stdout.write(` incremental: ${result.uploadedChunks} new chunks, ${result.uploadedBytes} compressed bytes uploaded, ${result.reusedBytes} source bytes reused\n`);
223
233
  }
@@ -57,6 +57,16 @@ export declare function backendFrom(broker: UploadCredentials): S3Backend;
57
57
  * says so.
58
58
  */
59
59
  export declare function nextVersion(backendUrl: string, refName: string, backend: DreamdbBackend, idField: string, idValue: string): Promise<number>;
60
+ export interface DreamdbHead {
61
+ nextVersion: number;
62
+ /** Optional bounded content from the newest matching row, in this snapshot. */
63
+ content: Uint8Array | null;
64
+ }
65
+ /** Read version and an optional small prior envelope from the same current
66
+ * broker-selected dataset snapshot. Never fetch a large historical raw blob.
67
+ * Ref/version read failures propagate; unavailable prior content merely
68
+ * disables the optimization, without guessing a new version number. */
69
+ export declare function readHead(backendUrl: string, refName: string, backend: DreamdbBackend, idField: string, idValue: string, maxContentBytes: number): Promise<DreamdbHead>;
60
70
  /**
61
71
  * A writer for the dataset, creating it on first push.
62
72
  *
@@ -68,6 +78,7 @@ export interface DreamdbRow {
68
78
  [field: string]: unknown;
69
79
  }
70
80
  export interface DreamdbIO {
81
+ readHead?(backendUrl: string, refName: string, backend: DreamdbBackend, idField: string, idValue: string, maxContentBytes: number): Promise<DreamdbHead>;
71
82
  nextVersion(backendUrl: string, refName: string, backend: DreamdbBackend, idField: string, idValue: string): Promise<number>;
72
83
  writeRow(backendUrl: string, refName: string, schema: SchemaField[], backend: DreamdbBackend, row: DreamdbRow): Promise<void>;
73
84
  }
@@ -106,6 +106,62 @@ export async function nextVersion(backendUrl, refName, backend, idField, idValue
106
106
  }
107
107
  return max + 1;
108
108
  }
109
+ /** Read version and an optional small prior envelope from the same current
110
+ * broker-selected dataset snapshot. Never fetch a large historical raw blob.
111
+ * Ref/version read failures propagate; unavailable prior content merely
112
+ * disables the optimization, without guessing a new version number. */
113
+ export async function readHead(backendUrl, refName, backend, idField, idValue, maxContentBytes) {
114
+ if (!Number.isSafeInteger(maxContentBytes) || maxContentBytes < 0)
115
+ throw new Error('Invalid prior content limit');
116
+ if (!(await datasetExists(backendUrl, refName, backend)))
117
+ return { nextVersion: 1, content: null };
118
+ const space = await Space.fromUri(refUri(backendUrl, refName), backend);
119
+ const anchors = (await space.queryScalar(idField, 'eq', idValue));
120
+ const wanted = new Set(anchors.map(String));
121
+ if (!wanted.size)
122
+ return { nextVersion: 1, content: null };
123
+ const column = await space.readScalarColumn(space.trackFor('version'), {});
124
+ let max = 0;
125
+ let anchor = null;
126
+ for (const [key, value] of column) {
127
+ if (!wanted.has(String(key)))
128
+ continue;
129
+ const version = Number(value);
130
+ if (!Number.isFinite(version))
131
+ continue;
132
+ if (version > max) {
133
+ max = version;
134
+ anchor = String(key);
135
+ }
136
+ else if (version === max)
137
+ anchor = null; // Ambiguous history: do not reuse.
138
+ }
139
+ const head = { nextVersion: max + 1, content: null };
140
+ if (!anchor)
141
+ return head;
142
+ try {
143
+ const track = space.tracks()
144
+ .find(t => String(t.modality).startsWith('image'));
145
+ if (!track)
146
+ return head;
147
+ const index = await space.resolveObjectIndex(track);
148
+ const hits = index.filter(e => e.length >= 4 && String(e[0]) === anchor && e[3] instanceof Uint8Array);
149
+ if (hits.length !== 1)
150
+ return head;
151
+ const hit = hits[0];
152
+ const size = Number(hit[2]);
153
+ if (!Number.isSafeInteger(size) || size < 0 || size > maxContentBytes)
154
+ return head;
155
+ const { bytes } = await backend.get(`${track.timeline}/${track.modality}/${ZERO_SPATIAL_KEY}/${bytesToBase32(hit[3])}`, { start: 0, end: maxContentBytes + 1 });
156
+ if (bytes.length <= maxContentBytes && bytes.length === size)
157
+ head.content = bytes;
158
+ }
159
+ catch {
160
+ // Missing/corrupt/unsupported prior content is repaired by a normal push.
161
+ // The version above came from a successful authoritative read, not a cache.
162
+ }
163
+ return head;
164
+ }
109
165
  /** Whether `refs/<refName>` is published — i.e. the dataset has been created. */
110
166
  async function datasetExists(backendUrl, refName, backend) {
111
167
  void backendUrl; // the ref key is relative to the dataset base
@@ -126,6 +182,7 @@ export async function openOrCreateWriter(backendUrl, refName, schema, backend) {
126
182
  return authoring.writer();
127
183
  }
128
184
  export const realDreamdbIO = {
185
+ readHead,
129
186
  nextVersion,
130
187
  async writeRow(backendUrl, refName, schema, backend, row) {
131
188
  const writer = await openOrCreateWriter(backendUrl, refName, schema, backend);
@@ -6,6 +6,7 @@
6
6
  // doesn't need the status.
7
7
  import { fail } from "../helpers.js";
8
8
  import { affiliateSuccessfulWrite } from '../session-affiliation.js';
9
+ import { noteAgentHeaders, resourceSessionHeaders } from '../agent-identity.js';
9
10
  import { resolveNamespace } from "./ctx.js";
10
11
  function headers(token, hasBody) {
11
12
  const h = {};
@@ -29,7 +30,7 @@ function isStaleConnection(e) {
29
30
  export async function jsonRequest(method, url, token, body) {
30
31
  const doFetch = () => fetch(url, {
31
32
  method,
32
- headers: headers(token, body !== undefined),
33
+ headers: { ...headers(token, body !== undefined), ...noteAgentHeaders(new URL(url).pathname), ...resourceSessionHeaders(new URL(url).pathname) },
33
34
  body: body !== undefined ? JSON.stringify(body) : undefined,
34
35
  });
35
36
  let res;
@@ -28,6 +28,8 @@ export interface DreamdbBackend {
28
28
  etag?: string;
29
29
  size?: number;
30
30
  }>;
31
+ /** Exact requested keys proven present; absence is never inferred from an incomplete listing. */
32
+ hasMany?(keys: readonly string[]): Promise<Set<string>>;
31
33
  put(key: string, bytes: Uint8Array, opts?: {
32
34
  ifMatch?: string;
33
35
  ifNoneMatchStar?: boolean;
@@ -71,6 +73,13 @@ export declare class S3Backend {
71
73
  etag?: string;
72
74
  size?: number;
73
75
  }>;
76
+ /**
77
+ * A bounded existence query for incremental chunks in THIS dataset. Published
78
+ * manifests are useful hints, not proof that their objects still exist.
79
+ * Never enumerate the dataset/history: at most four pages of the chunk prefix,
80
+ * then probe unresolved keys. Small/generic requests need only parallel HEADs.
81
+ */
82
+ hasMany(keys: readonly string[]): Promise<Set<string>>;
74
83
  /**
75
84
  * Conditional PUT. DreamDB publishes refs with a compare-and-swap, so the
76
85
  * precondition failures are expected control flow, not errors:
@@ -30,6 +30,65 @@ function unquote(etag) {
30
30
  return undefined;
31
31
  return etag.replace(/^"|"$/g, "");
32
32
  }
33
+ const CHUNK_KEY = /^artifact-chunks\/v1\/[a-f0-9]{64}\.gz$/;
34
+ const CHUNK_PREFIX = 'artifact-chunks/v1/';
35
+ const EXISTENCE_CONCURRENCY = 8;
36
+ const EXISTENCE_LIST_PAGES = 4;
37
+ const EXISTENCE_LIST_BYTES = 2 * 1024 * 1024;
38
+ /** S3 XML scalar values, including opaque continuation tokens. No entity expansion. */
39
+ function xmlValue(xml, tag) {
40
+ const matches = [...xml.matchAll(new RegExp(`<${tag}>([^<]*)<\\/${tag}>`, 'g'))];
41
+ if (matches.length > 1)
42
+ throw new Error(`Invalid S3 listing: duplicate ${tag}`);
43
+ const value = matches[0]?.[1];
44
+ if (value === undefined)
45
+ return undefined;
46
+ if (/&(?!(?:amp|lt|gt|quot|apos|#\d+|#x[0-9a-fA-F]+);)/.test(value))
47
+ throw new Error('Invalid S3 XML entity');
48
+ return value.replace(/&(amp|lt|gt|quot|apos|#\d+|#x[0-9a-fA-F]+);/g, (_, entity) => {
49
+ const named = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
50
+ if (named[entity] !== undefined)
51
+ return named[entity];
52
+ const point = entity.startsWith('#x') ? parseInt(entity.slice(2), 16) : Number(entity.slice(1));
53
+ if (!Number.isSafeInteger(point) || point <= 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff))
54
+ throw new Error('Invalid S3 XML character');
55
+ return String.fromCodePoint(point);
56
+ });
57
+ }
58
+ async function boundedResponseText(response, limit) {
59
+ if (Number(response.headers.get('content-length')) > limit) {
60
+ await response.body?.cancel();
61
+ throw new Error('S3 listing response exceeds its size bound');
62
+ }
63
+ if (!response.body)
64
+ return '';
65
+ const reader = response.body.getReader();
66
+ const parts = [];
67
+ let length = 0;
68
+ try {
69
+ while (true) {
70
+ const result = await reader.read();
71
+ if (result.done)
72
+ break;
73
+ length += result.value.length;
74
+ if (length > limit) {
75
+ await reader.cancel();
76
+ throw new Error('S3 listing response exceeds its size bound');
77
+ }
78
+ parts.push(result.value);
79
+ }
80
+ }
81
+ finally {
82
+ reader.releaseLock();
83
+ }
84
+ const bytes = new Uint8Array(length);
85
+ let offset = 0;
86
+ for (const part of parts) {
87
+ bytes.set(part, offset);
88
+ offset += part.length;
89
+ }
90
+ return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
91
+ }
33
92
  export class S3Backend {
34
93
  client;
35
94
  base;
@@ -78,6 +137,111 @@ export class S3Backend {
78
137
  size: len ? Number(len) : undefined,
79
138
  };
80
139
  }
140
+ /**
141
+ * A bounded existence query for incremental chunks in THIS dataset. Published
142
+ * manifests are useful hints, not proof that their objects still exist.
143
+ * Never enumerate the dataset/history: at most four pages of the chunk prefix,
144
+ * then probe unresolved keys. Small/generic requests need only parallel HEADs.
145
+ */
146
+ async hasMany(keys) {
147
+ const wanted = new Set(keys);
148
+ for (const key of wanted) {
149
+ if (!key || key.startsWith('/') || /[\\%?#\x00-\x1f\x7f]/.test(key) ||
150
+ key.split('/').some(segment => segment === '.' || segment === '..'))
151
+ throw new Error('Existence checks require canonical dataset-relative keys');
152
+ }
153
+ const found = new Set();
154
+ const probeRemaining = async () => {
155
+ const pending = [...wanted].filter(key => !found.has(key));
156
+ let next = 0;
157
+ let failure;
158
+ await Promise.all(Array.from({ length: Math.min(EXISTENCE_CONCURRENCY, pending.length) }, async () => {
159
+ while (next < pending.length && !failure) {
160
+ const key = pending[next++];
161
+ try {
162
+ const result = await this.head(key);
163
+ if (result.exists === true)
164
+ found.add(key);
165
+ else if (result.exists !== false)
166
+ throw new Error('Storage returned an indeterminate existence result');
167
+ }
168
+ catch (error) {
169
+ failure = error;
170
+ }
171
+ }
172
+ }));
173
+ if (failure)
174
+ throw failure;
175
+ return found;
176
+ };
177
+ if (wanted.size <= EXISTENCE_CONCURRENCY || [...wanted].some(key => !CHUNK_KEY.test(key)))
178
+ return probeRemaining();
179
+ const base = new URL(this.base);
180
+ const segments = base.pathname.replace(/^\/+|\/+$/g, '').split('/');
181
+ const bucket = segments.shift();
182
+ if (!bucket)
183
+ return probeRemaining();
184
+ const datasetPrefix = decodeURIComponent(segments.join('/'));
185
+ const relativePrefix = datasetPrefix ? `${datasetPrefix}/` : '';
186
+ const prefix = `${relativePrefix}${CHUNK_PREFIX}`;
187
+ const seenTokens = new Set();
188
+ let token;
189
+ for (let page = 0; page < EXISTENCE_LIST_PAGES; page++) {
190
+ const query = new URLSearchParams({ 'list-type': '2', prefix, 'max-keys': '1000', 'encoding-type': 'url' });
191
+ if (token)
192
+ query.set('continuation-token', token);
193
+ const response = await this.client.fetch(`${base.origin}/${bucket}?${query}`, { method: 'GET' });
194
+ const text = await boundedResponseText(response, response.ok ? EXISTENCE_LIST_BYTES : 64 * 1024);
195
+ if (!response.ok) {
196
+ const code = xmlValue(text, 'Code');
197
+ if (['ExpiredToken', 'InvalidToken', 'InvalidAccessKeyId', 'SignatureDoesNotMatch', 'TokenRefreshRequired', 'RequestExpired'].includes(code ?? ''))
198
+ throw new Error(`LIST artifact chunks → ${response.status} (${code})`);
199
+ // Some compatible stores deny listing but permit scoped object reads.
200
+ // Expired credentials, signature errors and transient failures propagate.
201
+ if ((response.status === 403 && (!code || code === 'AccessDenied')) ||
202
+ response.status === 405 || response.status === 501 ||
203
+ (response.status === 400 && ['NotImplemented', 'NotSupported', 'UnsupportedOperation'].includes(code ?? '')))
204
+ return probeRemaining();
205
+ throw new Error(`LIST artifact chunks → ${response.status}${code ? ` (${code})` : ''}`);
206
+ }
207
+ if (/<!DOCTYPE|<!ENTITY/i.test(text) || !/<ListBucketResult(?:\s[^>]*)?>/.test(text) || !/<\/ListBucketResult>\s*$/.test(text))
208
+ throw new Error('Invalid S3 listing response');
209
+ const encoding = xmlValue(text, 'EncodingType');
210
+ if (encoding !== undefined && encoding !== 'url')
211
+ throw new Error('Unsupported S3 listing encoding');
212
+ const decode = (value) => encoding === 'url' ? decodeURIComponent(value) : value;
213
+ if (decode(xmlValue(text, 'Prefix') ?? '') !== prefix)
214
+ throw new Error('S3 listing returned a different prefix');
215
+ const truncated = xmlValue(text, 'IsTruncated');
216
+ if (truncated !== 'true' && truncated !== 'false')
217
+ throw new Error('Invalid S3 listing truncation status');
218
+ const contents = [...text.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)];
219
+ if (contents.length > 1000 || /<Contents\s*\/>/.test(text) || (text.match(/<Contents(?:\s|>)/g) ?? []).length !== contents.length ||
220
+ (text.match(/<\/Contents>/g) ?? []).length !== contents.length)
221
+ throw new Error('Invalid S3 listing contents/page bound');
222
+ const keyCount = xmlValue(text, 'KeyCount');
223
+ if (keyCount !== undefined && (!/^\d+$/.test(keyCount) || Number(keyCount) !== contents.length))
224
+ throw new Error('S3 listing key count mismatch');
225
+ for (const entry of contents) {
226
+ const raw = xmlValue(entry[1], 'Key');
227
+ if (raw === undefined)
228
+ throw new Error('S3 listing entry is missing its key');
229
+ const key = decode(raw);
230
+ if (!key.startsWith(prefix))
231
+ throw new Error('S3 listing returned a key outside its prefix');
232
+ const relative = key.slice(relativePrefix.length);
233
+ if (wanted.has(relative))
234
+ found.add(relative);
235
+ }
236
+ if (found.size === wanted.size || truncated === 'false')
237
+ return found;
238
+ token = xmlValue(text, 'NextContinuationToken');
239
+ if (!token || token.length > 16 * 1024 || seenTokens.has(token))
240
+ throw new Error('Invalid S3 listing continuation token');
241
+ seenTokens.add(token);
242
+ }
243
+ return probeRemaining();
244
+ }
81
245
  /**
82
246
  * Conditional PUT. DreamDB publishes refs with a compare-and-swap, so the
83
247
  * precondition failures are expected control flow, not errors:
@@ -92,6 +92,7 @@ export const helpExamples = {
92
92
  "notes visit": "# Reuse the task's DREAMLAKE_AGENT_ID and DREAMLAKE_AGENT_NAME.\nNOTE_ID=release-plan\ndreamlake notes visit \"$NOTE_ID\"",
93
93
  "notes presence": "# Read the participant roster without joining. Text is the default.\nNOTE_ID=release-plan\ndreamlake notes presence \"$NOTE_ID\"",
94
94
  "notes select": "export DREAMLAKE_AGENT_ID=\"review-session-42\"\nexport DREAMLAKE_AGENT_NAME=\"Codex\"\nNOTE_ID=\"your-note-id\"\ndreamlake notes select --text \"The next step is tested in simulation.\" --note \"$NOTE_ID\"\n# Select the last occurrence of a repeated passage.\ndreamlake notes select --text \"simulation\" --note \"$NOTE_ID\" -o -1",
95
+ "notes contributors": "dreamlake notes contributors release-plan --namespace geyang --json\n# If hasMore is true, continue with the returned nextCursor:\ndreamlake notes contributors release-plan --namespace geyang --cursor LINK_CURSOR --json",
95
96
  "notes rm": "# Read it first and confirm it is the note you mean.\ndreamlake notes read NOTE_ID\n# Asks for confirmation, showing the title and owning namespace.\ndreamlake notes rm NOTE_ID\n# Scripts and agents: skip the prompt and take a JSON receipt.\ndreamlake notes rm NOTE_ID --yes --json\n# Afterwards a read reports not found.\ndreamlake notes read NOTE_ID",
96
97
  "notes patch": "set -euo pipefail\ndreamlake notes create \"Patch tutorial\" --text 'Hello world.' > created.txt\nNOTE_ID=$(sed -n 's/^ id //p' created.txt)\ndreamlake notes read \"$NOTE_ID\" --view source --json > baseline.json\n# A plain text read is the mapped reading view and --view source is bytes only;\n# --json is the structured snapshot with note, hash and revision.\nBASE=$(jq -er .revision baseline.json)\ndreamlake notes patch \"$NOTE_ID\" --file - --base-revision \"$BASE\" --json > receipt.json <<'PATCH'\n@@ chars 0:12 @@\n~ Hello [-world-]{+team+}.\nPATCH\nACK=$(jq -er .revision receipt.json)\ndreamlake notes read \"$NOTE_ID\" --if-match \"$ACK\"\n# Expect Hello team. Inspect the result; do not repeat a successful patch.",
97
98
  "notes append": "dreamlake notes append \"$NOTE_ID\" --file addition.md --base-revision \"$BASE\" --json\n# ACK is the revision in the successful append receipt.\ndreamlake notes read \"$NOTE_ID\" --at \"$ACK\"",
@@ -116,6 +116,11 @@ export declare function runNotesDiff(ref: string | undefined, opts: DocumentRead
116
116
  }): Promise<number>;
117
117
  export declare function runNotesPatch(ref: string, opts: DocumentPatchOptions): Promise<number>;
118
118
  /** Reading the roster never registers presence or maintains a session. */
119
+ export declare function runNotesContributors(ref: string, opts: ConnOpts & {
120
+ json?: boolean;
121
+ cursor?: string;
122
+ }): Promise<number>;
123
+ /** Reading the roster never registers presence or maintains a session. */
119
124
  export declare function runNotesPresence(ref: string, opts: ConnOpts & {
120
125
  json?: boolean;
121
126
  }): Promise<number>;
@@ -218,6 +218,13 @@ export function registerNotesCommand(program) {
218
218
  .option("--namespace <slug>", "note owner namespace")
219
219
  .option("--json", "emit JSON for programmatic consumers")
220
220
  .action(async (note, opts) => { process.exitCode = await runNotesPresence(note, opts); });
221
+ strict(notes.command("contributors"))
222
+ .argument("<note>", "note id, slug or title")
223
+ .description("list durable contributing sessions and explicitly linked sessions")
224
+ .option("--namespace <slug>", "note owner namespace")
225
+ .option("--cursor <id>", "continue from the returned nextCursor")
226
+ .option("--json", "emit JSON including evidence and pagination")
227
+ .action(async (note, opts) => { process.exitCode = await runNotesContributors(note, opts); });
221
228
  strict(notes.command("projects"))
222
229
  .argument("<note-id>", "stable Note ID")
223
230
  .description("inspect current project filing and server-computed filing permissions (JSON)")
@@ -1307,6 +1314,32 @@ export async function runNotesPatch(ref, opts) {
1307
1314
  return opts.legacy ? runLegacyNotesPatch(ref, opts) : runDocumentPatch(ref, opts);
1308
1315
  }
1309
1316
  /** Reading the roster never registers presence or maintains a session. */
1317
+ export async function runNotesContributors(ref, opts) {
1318
+ const c = await ctx(opts);
1319
+ if (!c)
1320
+ return 1;
1321
+ try {
1322
+ const id = await resolveNote(c, ref);
1323
+ if (!id)
1324
+ return 1;
1325
+ const result = await notePresenceApi(noteTransport(c), `/namespaces/${seg(c.ns)}/notes`).contributors(id, { cursor: opts.cursor });
1326
+ if (opts.json)
1327
+ emitJson(result);
1328
+ else {
1329
+ for (const session of result.sessions)
1330
+ process.stdout.write(`${session.name}\t${session.contribution?.kind ?? 'linked'}\t${session.namespaceSlug}/${session.id}\n`);
1331
+ if (!result.sessions.length)
1332
+ process.stdout.write('No accessible contributing sessions recorded.\n');
1333
+ if (result.nextCursor)
1334
+ process.stdout.write(`Continue with --cursor ${result.nextCursor}\n`);
1335
+ }
1336
+ return 0;
1337
+ }
1338
+ catch (error) {
1339
+ return report(error);
1340
+ }
1341
+ }
1342
+ /** Reading the roster never registers presence or maintains a session. */
1310
1343
  export async function runNotesPresence(ref, opts) {
1311
1344
  const c = await ctx(opts);
1312
1345
  if (!c)
@@ -67,6 +67,12 @@ export function createAutoAffiliator(deps = {}) {
67
67
  const address = new URL(url), resource = writtenResource(method, address.pathname, response, payload);
68
68
  if (!resource)
69
69
  return;
70
+ // The Note server records confirmed changes using presence/session headers.
71
+ // A second client-side link cannot prove a write (notably no-op/replayed receipts).
72
+ // Explicit conversation upload remains opt-in and never replays content.
73
+ if (resource.type === 'note' && (!env.DREAMLAKE_CONVERSATION_FILE ||
74
+ response?.outcome === 'no-write'))
75
+ return;
70
76
  if (env.DREAMLAKE_SESSION_VISIBILITY && !['public', 'private'].includes(env.DREAMLAKE_SESSION_VISIBILITY))
71
77
  throw new Error('DREAMLAKE_SESSION_VISIBILITY must be public or private; metadata was not published');
72
78
  const key = JSON.stringify([address.origin, token, resource, context]);
@@ -1 +1 @@
1
- export declare const VERSION = "0.102.0";
1
+ export declare const VERSION = "0.102.2";
@@ -6,4 +6,4 @@
6
6
  // value means a binary that re-installs the same version forever.
7
7
  //
8
8
  // Editing this by hand does nothing for a release; bump package.json.
9
- export const VERSION = "0.102.0";
9
+ export const VERSION = "0.102.2";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dreamlake/dreamlake-cli",
3
- "version": "0.102.0",
3
+ "version": "0.102.2",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/dreamlake-ai/dreamlake-cli.git"
@@ -36,13 +36,13 @@
36
36
  "node": ">=18"
37
37
  },
38
38
  "optionalDependencies": {
39
- "@dreamlake/dreamlake-cli-darwin-arm64": "0.102.0",
40
- "@dreamlake/dreamlake-cli-darwin-x64": "0.102.0",
41
- "@dreamlake/dreamlake-cli-linux-x64": "0.102.0",
42
- "@dreamlake/dreamlake-cli-linux-arm64": "0.102.0",
43
- "@dreamlake/dreamlake-cli-linux-x64-musl": "0.102.0",
44
- "@dreamlake/dreamlake-cli-linux-arm64-musl": "0.102.0",
45
- "@dreamlake/dreamlake-cli-win32-x64": "0.102.0",
46
- "@dreamlake/dreamlake-cli-win32-arm64": "0.102.0"
39
+ "@dreamlake/dreamlake-cli-darwin-arm64": "0.102.2",
40
+ "@dreamlake/dreamlake-cli-darwin-x64": "0.102.2",
41
+ "@dreamlake/dreamlake-cli-linux-x64": "0.102.2",
42
+ "@dreamlake/dreamlake-cli-linux-arm64": "0.102.2",
43
+ "@dreamlake/dreamlake-cli-linux-x64-musl": "0.102.2",
44
+ "@dreamlake/dreamlake-cli-linux-arm64-musl": "0.102.2",
45
+ "@dreamlake/dreamlake-cli-win32-x64": "0.102.2",
46
+ "@dreamlake/dreamlake-cli-win32-arm64": "0.102.2"
47
47
  }
48
48
  }