@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/manifest-write.d.ts

@@ -0,0 +1,161 @@
+import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+import { type FindOptions } from "./drive-paths.ts";
+import { type OnCollision } from "./collision.ts";
+import { type ManifestIntent, type SettingsPatch } from "./shared/lib/drive/manifest-ops.ts";
+/**
+ * ⛔ THE SAME FIELD NAMES `Session` USES, so a session IS a valid input and nothing has to be
+ *    translated between the two. One thing with two names is how a caller ends up passing the
+ *    server where the account id goes on the day a field moves.
+ */
+export interface ListEditInput {
+    server: string;
+    apiKey: string;
+    code: string;
+    accountId: string;
+}
+export interface ListEditResult {
+    /** The version now current. */
+    seq: number;
+    /** True when the list was rebuilt because another device wrote first. */
+    reappliedAfterConflict: boolean;
+    /** False when the intent was already true of the list, so nothing was written. */
+    changed: boolean;
+    /** The list as it now stands — after the edit, or as found when nothing changed. */
+    entries: readonly ManifestEntry[];
+}
+/**
+ * Apply one intent to the account's sealed file list.
+ *
+ * ⛔ THE INTENT IS WHAT IS RETRIED, NEVER FINISHED BYTES. On a lost compare-and-swap the list is
+ *    read again and the intent is applied to the NEW one, so both edits survive. That is why the
+ *    caller passes a function rather than an intent: an intent computed once against the old list
+ *    could name a folder id, or a free name, that the new list no longer has.
+ *
+ * ⛔ AND THE INTENTS COME FROM THE BROWSER'S OWN MODULE, copied here byte-for-byte by
+ *    `deploy/gen-cli-shared.mjs`. Re-implementing "send to the trash" would look trivial and be
+ *    wrong in the small places: a re-trashed item must keep its ORIGINAL instant (it is the start
+ *    of the 30-day window the product promises), and trashing a folder must not stamp its
+ *    children (that would reset each child's own clock).
+ *
+ * `make` returning null means there is nothing to do; nothing is written and `changed` is false.
+ */
+export declare function applyToList(input: ListEditInput, make: (entries: readonly ManifestEntry[]) => ManifestIntent | null): Promise<ListEditResult>;
+/**
+ * Apply a RUN of intents to the account's sealed file list — as ONE write.
+ *
+ * ⛔ ONE WRITE, NOT ONE PER TARGET. A command naming five things and writing five times is five
+ *    chances to lose the compare-and-swap, and losing it half way leaves a drive nobody asked
+ *    for: three things moved, two not, and one error that names neither half. The whole list is
+ *    rewritten on every save anyway (see the header), so five edits cost exactly what one costs.
+ *
+ * ⛔ AND `make` DECIDES THE WHOLE RUN AGAIN ON EVERY ATTEMPT. A free name, an existing folder and
+ *    a live target are all facts about the version that was READ, and a retry happens against a
+ *    version somebody else has just written. A `make` that folds its own intents onto a working
+ *    copy as it goes must start that fold from the list it is handed each time — never from the
+ *    working copy it built on the attempt before.
+ *
+ * An empty run means there is nothing to do; nothing is written and `changed` is false.
+ *
+ * ⛔ AND THE ACCOUNT'S SETTINGS RIDE IN THE SAME WRITE. They live in this blob or nowhere (see the
+ *    header), so a caller that wanted to change one and did it in a second write would spend two
+ *    version bumps and two chances to lose the compare-and-swap on one edit. `patch` is DESIRED
+ *    STATE per field, like every intent above, so replaying it after a lost swap lands the same
+ *    answer. Absent means "carry the settings forward untouched", which is what every caller but
+ *    one wants.
+ */
+export declare function applyManyToList(input: ListEditInput, make: (entries: readonly ManifestEntry[]) => readonly ManifestIntent[], patch?: SettingsPatch): Promise<ListEditResult>;
+/**
+ * The entries a run of typed paths names, in the order they were typed.
+ *
+ * ⛔ HERE, BESIDE THE BATCH WRITE, so every command that takes many paths answers "the same thing
+ *    named twice" the same way: once. `nmts rm a.txt a.txt` is not two deletions, and a repeated
+ *    id inside one intent would make the count in the message disagree with the list written.
+ *
+ * ⛔ AND A PATH THAT DOES NOT RESOLVE REFUSES THE WHOLE RUN, because it throws from here before
+ *    anything is composed. That is the decision every batch command in this tool makes: nothing
+ *    is half-done. Moving the four paths that resolved and skipping the fifth would exit 0 on a
+ *    command that did not do what it was told, and the caller would have to diff the drive to
+ *    find out which one. A path already IN the state being asked for is not this case — that is
+ *    a no-op, and each command names it in its own words.
+ *
+ * ⚠ Call it INSIDE `make`. A path is a question about the list, and the answer changes when
+ *   another device writes first.
+ */
+export declare function batchTargets(entries: readonly ManifestEntry[], paths: readonly string[], options?: FindOptions): ManifestEntry[];
+export interface AddEntryInput extends ListEditInput {
+    /** The entry to add. Its `name` may be changed to avoid a collision — see the result. */
+    entry: ManifestEntry;
+    /**
+     * What THIS run asked for when the name is already in use. Absent = whatever this machine is
+     * set to (`collision.ts`), which is what an ordinary upload wants.
+     */
+    onCollision?: OnCollision;
+}
+export interface AddEntryResult {
+    /** The version now current. */
+    seq: number;
+    /** The name the entry actually got, which is not the requested one if that was taken. */
+    name: string;
+    /** True when the list was rebuilt because another device wrote first. */
+    reappliedAfterConflict: boolean;
+    /**
+     * The file this one displaced, when the name was taken and the answer was to overwrite.
+     *
+     * ⛔ IT IS IN THE TRASH, NOT GONE. This tool cannot destroy a stored row: the endpoint that does
+     *    is closed to an API key on purpose (`item-trash.ts`). So the caller's remaining job is to
+     *    tell the SERVER to trash it too — and what the tool prints must say "trash", never "gone".
+     */
+    replaced?: {
+        id: string;
+        name: string;
+    };
+}
+/** What one addition turns into, worked out against the list as it stands on THIS attempt. */
+export interface AdditionPlan {
+    /** The name it will be stored under. */
+    name: string;
+    /** Set when this id is ALREADY in the list — then `intents` is empty and nothing is written. */
+    alreadyThere?: string;
+    /** The live file this displaces, when the name was taken and the answer was to overwrite. */
+    replaced?: {
+        id: string;
+        name: string;
+    };
+    intents: ManifestIntent[];
+}
+/**
+ * Decide what adding this entry does — the whole of the collision rule, with no server in it.
+ *
+ * ⛔ IT IS RE-RUN ON EVERY COMPARE-AND-SWAP ATTEMPT, so everything it looks at has to come from
+ *    the `entries` it is handed. A free name, a live holder and a folder id are all facts about
+ *    the version that was READ, and a retry happens against a version somebody else just wrote.
+ *
+ * ⛔ ONLY A LIVE FILE IS DISPLACED. A folder can hold the name, and replacing one would mean
+ *    deleting it and everything under it in order to store a single file. A trashed file holds its
+ *    name too, and displacing THAT would destroy something already on its way out for a name the
+ *    person can no longer see. Both are renamed around, with no answer consulted — which is what
+ *    happened to every collision before anything could be answered at all.
+ */
+export declare function planAddition(entries: readonly ManifestEntry[], entry: ManifestEntry, 
+/**
+ * The ANSWER, already settled — not what a run asked for.
+ *
+ * ⛔ WHO IS ALLOWED TO SAY "OVERWRITE" IS `collision.ts`'s JOB, not this one's. It weighs the
+ *    machine's stored answer, what the run asked for, and whether a mode lets an agent decide
+ *    for itself. Re-deriving any of that here would be a second place for the owner's rule to
+ *    live, and the copy nobody re-reads is the one that quietly disagrees.
+ */
+choice: OnCollision, now?: number): AdditionPlan;
+/**
+ * Add one entry to the account's sealed file list.
+ *
+ * ⛔ THE NAME IS CHOSEN AGAINST THE LIST AS IT IS ON THIS ATTEMPT. That is the reason this passes
+ *    a function to `applyManyToList`: after a lost compare-and-swap the free names have changed,
+ *    and a name picked against the old list could land on top of what the other device just added.
+ *    The collision is judged again on every attempt for the same reason.
+ *
+ * ⛔ ONLY A LIVE FILE IS DISPLACED. A folder can hold the name, and replacing one would mean
+ *    deleting it and everything under it in order to store a single file. Those are renamed, with
+ *    no answer consulted, exactly as every collision was before anything could be answered at all.
+ */
+export declare function addEntry(input: AddEntryInput): Promise<AddEntryResult>;

package/dist/manifest-write.js

@@ -5,8 +5,10 @@
 //    sealed under a key the server does not have. So this is the last step of an upload and the
 //    one that must not be skipped after the money moved.
 //
-// ⛔ THE WHOLE LIST IS REWRITTEN EVERY TIME. There is no "append" on the wire — the blob is sealed
-//    as one piece. That is why this re-reads immediately before writing: the version it builds on
+// ⛔ THE WHOLE LIST IS DECIDED EVERY TIME, EVEN THOUGH ONLY PART OF IT IS SENT. There is no
+//    "append" on the wire: the entries this save means to leave behind are worked out in full and
+//    then packed into chunks, and only the chunks whose contents actually changed are written
+//    (NCF-3 §6.3). That is why this re-reads immediately before writing — the version it builds on
 //    has to be the current one, and anything another device added since must be carried forward,
 //    not overwritten.
 //
@@ -17,14 +19,14 @@
 //      · the `prev` link inside the blob makes a fork visible to the NEXT reader on any device.
 //    The account's own settings ride along for the same reason: they live in this blob or nowhere,
 //    so rewriting the list without them would silently clear them.
-import { request, ServerError } from "./api.js";
-import { AAD, DERIVED, loadCrypto } from "./crypto.js";
+import { ServerError } from "./api.js";
+import { DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
+import { writeChunkedList } from "./manifest-chunk-flow.js";
 import { readFileList, recordWrittenList } from "./manifest.js";
-import { encodeManifest } from "./shared/lib/drive/manifest-codec.js";
 import { buildIndex, entryAt, isLive, KIND_FILE, namesIn, normaliseName } from "./drive-paths.js";
 import { decide } from "./collision.js";
-import { applyIntents } from "./shared/lib/drive/manifest-ops.js";
+import { applyIntents, applySettingsPatch, } from "./shared/lib/drive/manifest-ops.js";
 import { uniqueFileName } from "./shared/lib/drive/unique-name.js";
 /** How many times a lost compare-and-swap is re-applied before giving up. */
 const CONFLICT_RETRIES = 3;
@@ -68,8 +70,15 @@ export async function applyToList(input, make) {
  *    working copy it built on the attempt before.
  *
  * An empty run means there is nothing to do; nothing is written and `changed` is false.
+ *
+ * ⛔ AND THE ACCOUNT'S SETTINGS RIDE IN THE SAME WRITE. They live in this blob or nowhere (see the
+ *    header), so a caller that wanted to change one and did it in a second write would spend two
+ *    version bumps and two chances to lose the compare-and-swap on one edit. `patch` is DESIRED
+ *    STATE per field, like every intent above, so replaying it after a lost swap lands the same
+ *    answer. Absent means "carry the settings forward untouched", which is what every caller but
+ *    one wants.
  */
-export async function applyManyToList(input, make) {
+export async function applyManyToList(input, make, patch) {
     const crypt = await loadCrypto();
     const [from, to] = DERIVED.fileListKey;
     const derived = crypt.kdf_derive(crypt.account_code_parse(input.code));
@@ -80,30 +89,40 @@ export async function applyManyToList(input, make) {
         for (let attempt = 0; attempt <= CONFLICT_RETRIES; attempt += 1) {
             const current = await readFileList(input.server, input.apiKey, input.code, input.accountId);
             const entries = current.manifest ? current.manifest.entries : [];
+            // ⛔ THE SAME REFERENCE COMES BACK WHEN NOTHING CHANGED, which is what the no-op test below
+            //    reads. `applySettingsPatch` promises that, and the empty object stands in for an
+            //    account that has never written a setting so that the comparison has something to hold.
+            const held = current.manifest?.settings ?? {};
+            const settings = patch === undefined ? held : applySettingsPatch(held, patch);
             const intents = make(entries);
+            const next = intents.length === 0 ? entries : applyIntents(entries, intents);
             // ⛔ A no-op is a SUCCESS, not a failure. Renaming a file to the name it already has, or
             //    trashing something already in the trash, must not cost a version bump every other
             //    device then has to download.
-            if (intents.length === 0) {
-                return { seq: current.seq ?? 0, reappliedAfterConflict: conflicted, changed: false, entries };
-            }
-            const next = applyIntents(entries, intents);
-            if (next === entries) {
+            if (next === entries && settings === held) {
                 return { seq: current.seq ?? 0, reappliedAfterConflict: conflicted, changed: false, entries };
             }
-            const body = await encodeManifest(next, (current.seq ?? 0) + 1, current.fingerprint, current.manifest?.settings);
-            const sealed = crypt.envelope_seal(key, new TextEncoder().encode(AAD.fileList), body);
-            body.fill(0);
-            const ct = Buffer.from(sealed).toString("base64url");
+            const io = {
+                server: input.server,
+                apiKey: input.apiKey,
+                accountId: input.accountId,
+                crypt,
+                key,
+            };
             try {
-                const answer = await request(input.server, "/v1/manifest", {
-                    method: "PUT",
-                    token: input.apiKey,
-                    body: { base_seq: current.seq ?? null, ct },
+                // ⛔ ALWAYS VERSION 2 (NCF-3 §6.3.6). A list read as version 1 has no chunks to build on,
+                //    so it is packed from scratch and the index names the version-1 blob as its parent —
+                //    the link crosses the version boundary unchanged, and the account is converted.
+                const written = await writeChunkedList(io, {
+                    previous: current.chunks ?? [],
+                    entries: next,
+                    seq: (current.seq ?? 0) + 1,
+                    ...(current.fingerprint !== undefined ? { prev: current.fingerprint } : {}),
+                    settings,
+                    baseSeq: current.seq ?? null,
                 });
-                const seq = seqOf(answer);
-                await recordWrittenList(input.accountId, seq, ct);
-                return { seq, reappliedAfterConflict: conflicted, changed: true, entries: next };
+                await recordWrittenList(input.accountId, written.seq, written.ct);
+                return { seq: written.seq, reappliedAfterConflict: conflicted, changed: true, entries: next };
             }
             catch (error) {
                 // ⛔ A version conflict is an ORDINARY outcome, not a failure: another device wrote first.
@@ -232,13 +251,3 @@ export async function addEntry(input) {
         ...(replaced ? { replaced } : {}),
     };
 }
-function seqOf(answer) {
-    if (typeof answer === "object" && answer !== null) {
-        const seq = Reflect.get(answer, "seq");
-        if (typeof seq === "number" && Number.isSafeInteger(seq) && seq >= 1)
-            return seq;
-    }
-    throw new NmtsError("The file list was written but the server did not say which version it is now.", {
-        nextStep: "The entry is saved. Run `nmts ls` to see it.",
-    });
-}

package/dist/manifest.d.ts

@@ -0,0 +1,82 @@
+import type { Manifest } from "./shared/lib/drive/manifest-codec.ts";
+import type { HeldChunk } from "./shared/lib/drive/manifest-pack.ts";
+import type { AccountSettings } from "./shared/lib/drive/manifest-settings.ts";
+import type { PaddingRule } from "./shared/lib/crypto/size-padding.ts";
+/** This machine's copy of one account's sealed file list. */
+/**
+ * Which size-padding rule an account's settings select for what this run seals.
+ *
+ * ⛔ ONE PLACE, because four commands seal uploads. A rule read four ways is a rule some of them
+ *    eventually get wrong, and the way it shows up is that an account which asked to store files
+ *    at their exact size quietly pays for rounded-up bytes from one command and not another.
+ *
+ * A spelling this build does not know reads as the DEFAULT rather than as "no padding": sealing by
+ * a rule this copy cannot reproduce would give a file a size no reader here can account for.
+ */
+export declare function paddingRuleOf(settings: AccountSettings | undefined): PaddingRule;
+export interface KeptList {
+    /** The version these bytes carry. Higher is newer — the same counter every device syncs by. */
+    seq: number;
+    /** When THIS MACHINE wrote the copy, RFC3339 on its own clock. */
+    savedAt: string;
+    /** The sealed blob, base64url: exactly the bytes the server served or this tool wrote. */
+    ct: string;
+}
+/**
+ * The copy this machine holds for an account, or null when it holds none.
+ *
+ * ⚠ A COPY THAT CANNOT BE READ IS REPORTED AS NO COPY, on purpose. There is nothing to salvage
+ *   from a truncated one, the next read of the list replaces it, and a command that refused to
+ *   write out a good copy because an old one is unreadable would be refusing the very thing it is
+ *   for.
+ */
+export declare function readKeptList(accountId: string): KeptList | null;
+/**
+ * Record a version this machine WROTE, so the server cannot serve an older one back afterwards.
+ *
+ * ⛔ ONLY AFTER THE SERVER ACCEPTED IT. Recording a version that lost the compare-and-swap would
+ *    leave this machine believing in a list that never existed — and then refusing the real one as
+ *    a rollback.
+ */
+export declare function recordWrittenList(accountId: string, seq: number, ct: string): Promise<void>;
+/** True when this machine has a record for the account — i.e. a rollback would be visible. */
+export declare function hasSeenBefore(accountId: string): boolean;
+export interface FileList {
+    /** null when the account has no list yet — a new account, not an error. */
+    manifest: Manifest | null;
+    /**
+     * base64url SHA-256 of the sealed blob this list came out of. Absent with no list.
+     *
+     * ⛔ A WRITER NEEDS IT. The next version has to name the blob it continued from, or the fork
+     *    check has a hole exactly where a fork would be introduced.
+     */
+    fingerprint?: string;
+    /** The version the sealed blob itself claims. Absent with no list. */
+    seq?: number;
+    /** What the server's column said, when it disagreed with the sealed value. */
+    serverSeqDisagreed?: number;
+    /** True when nothing on this machine could have caught a rollback. */
+    firstTimeOnThisMachine: boolean;
+    /**
+     * The sealed format this list turned out to be: 1 for the single blob, 2 for index plus chunks.
+     *
+     * ⚠ READERS ACCEPT BOTH; WRITERS WRITE 2 (NCF-3 §6.3). An account converts on its first save by
+     *   a build that knows version 2, and nothing converts on read.
+     */
+    version?: number;
+    /**
+     * Version 2 only: the chunks this list was read out of, in placement order.
+     *
+     * ⛔ A WRITER NEEDS THEM. Comparing the new entries against these is what lets a save rewrite the
+     *    one chunk that changed instead of the whole list. Empty means "there are none to build on",
+     *    which is both a version-1 list and an account with no items — and both pack from scratch.
+     */
+    chunks?: readonly HeldChunk[];
+}
+/**
+ * Fetch and open the account's file list.
+ *
+ * `accountCode` is used here and not kept: the file-list key is derived, used, and zeroed. The
+ * derivation output holds every other key in the account, so it does not outlive this call.
+ */
+export declare function readFileList(base: string, apiKey: string, accountCode: string, accountId: string): Promise<FileList>;

package/dist/manifest.js

@@ -16,18 +16,25 @@
 //
 // ⛔ AND THE SEALED BYTES THEMSELVES ARE KEPT, beside that record. The record alone is a detector:
 //    it can tell that a list went backwards, and it cannot hand anybody a list. The blob can — it
-//    is the account's names, folders and file keys, sealed with the account code, and a copy of it
+//    is the account's names, folders and file keys, sealed with the NMTS key, and a copy of it
 //    on this machine is one of the two things a person needs when the server has nothing to give
 //    them. A tool that read the list on every run and then threw it away left an account used only
 //    from a terminal with neither. It is written with the record, by the one function that writes
 //    either, so the two can never describe different versions.
+//
+// ⛔ AT FORMAT VERSION 2 THOSE BYTES ARE THE INDEX, AND THE ENTRIES ARE BESIDE IT. The list is an
+//    index plus immutable chunks named by their own hash (NCF-3 §6.3); the index is kept here
+//    exactly as the single blob was, and the chunks are kept by name in the chunk store
+//    (`manifest-chunk-cache.ts`), which is pruned to what the list just read names. So the copy is
+//    still complete — it is simply in two places, and `nmts listfile` writes them out as one file.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { request } from "./api.js";
 import { AAD, DERIVED, loadCrypto } from "./crypto.js";
 import { configDir } from "./credentials.js";
 import { NmtsError } from "./errors.js";
-import { decodeManifest } from "./shared/lib/drive/manifest-codec.js";
+import { openChunks } from "./manifest-chunk-flow.js";
+import { decodeFileList, FILE_LIST_VERSION_CHUNKED, } from "./shared/lib/drive/manifest-chunks.js";
 function asResponse(value) {
     if (typeof value !== "object" || value === null)
         throw new NmtsError("The server's answer was not an object.");
@@ -67,6 +74,21 @@ function keptListPath(accountId) {
     }
     return join(configDir(), `file-list-${accountId}.json`);
 }
+/** This machine's copy of one account's sealed file list. */
+/**
+ * Which size-padding rule an account's settings select for what this run seals.
+ *
+ * ⛔ ONE PLACE, because four commands seal uploads. A rule read four ways is a rule some of them
+ *    eventually get wrong, and the way it shows up is that an account which asked to store files
+ *    at their exact size quietly pays for rounded-up bytes from one command and not another.
+ *
+ * A spelling this build does not know reads as the DEFAULT rather than as "no padding": sealing by
+ * a rule this copy cannot reproduce would give a file a size no reader here can account for.
+ */
+export function paddingRuleOf(settings) {
+    const mode = settings?.paddingMode;
+    return mode === "pow2" || mode === "none" ? mode : "padme";
+}
 function isKeptList(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -186,28 +208,54 @@ export async function readFileList(base, apiKey, accountCode, accountId) {
     const derived = crypt.kdf_derive(crypt.account_code_parse(accountCode));
     const key = derived.slice(from, to);
     derived.fill(0);
-    let body;
+    // ⛔ THE KEY LIVES UNTIL THE CHUNKS ARE OPEN. A version-2 list is an index plus sealed chunks
+    //    under a label of their own, so the same key opens two kinds of blob and the zeroing has to
+    //    wait for the second kind — which is why one `finally` now wraps the whole read.
     try {
-        body = crypt.envelope_open(key, new TextEncoder().encode(AAD.fileList), Buffer.from(answer.ct, "base64url"));
-    }
-    catch {
-        throw new NmtsError("The file list did not open with this account's key.", {
-            nextStep: "Either the code belongs to a different account, or the stored bytes are not what this " +
-                "account sealed. Nothing was changed.",
-        });
+        let body;
+        try {
+            body = crypt.envelope_open(key, new TextEncoder().encode(AAD.fileList), Buffer.from(answer.ct, "base64url"));
+        }
+        catch {
+            throw new NmtsError("The file list did not open with this account's key.", {
+                nextStep: "Either the NMTS key belongs to a different account, or the stored bytes are not what this " +
+                    "account sealed. Nothing was changed.",
+            });
+        }
+        const doc = await decodeFileList(body);
+        body.fill(0);
+        const io = { server: base, apiKey, accountId, crypt, key };
+        // A version-1 blob carries its own entries; a version-2 index names chunks that have to be
+        // fetched, checked against the names it gave them, and read end to end (§6.3.2).
+        const chunks = doc.v === FILE_LIST_VERSION_CHUNKED ? await openChunks(io, doc.index) : [];
+        const manifest = doc.v === FILE_LIST_VERSION_CHUNKED
+            ? {
+                v: FILE_LIST_VERSION_CHUNKED,
+                seq: doc.index.seq,
+                ...(doc.index.p !== undefined ? { prev: doc.index.p } : {}),
+                entries: chunks.flatMap((c) => [...c.items]),
+                ...(doc.index.settings !== undefined ? { settings: doc.index.settings } : {}),
+            }
+            : doc.manifest;
+        const out = {
+            manifest,
+            seq: manifest.seq,
+            fingerprint: fp,
+            firstTimeOnThisMachine: first,
+            version: doc.v,
+            chunks,
+        };
+        // ⛔ The sealed number is the authenticated one, so it is what gets recorded and what a later
+        //    run compares against. The column is reported when it differs and otherwise ignored.
+        if (manifest.seq !== answer.seq)
+            out.serverSeqDisagreed = answer.seq;
+        // ⛔ THE VERSION THAT IS KEPT IS THE SEALED ONE, and so are the bytes it came out of. Believing
+        //    the server's column here would let it decide which copy this machine keeps. The bytes are
+        //    the INDEX at version 2; its chunks are kept beside it, by name, in the chunk store.
+        writeSeen(accountId, manifest.seq, fp, answer.ct);
+        return out;
     }
     finally {
         key.fill(0);
     }
-    const manifest = await decodeManifest(body);
-    body.fill(0);
-    const out = { manifest, seq: manifest.seq, fingerprint: fp, firstTimeOnThisMachine: first };
-    // ⛔ The sealed number is the authenticated one, so it is what gets recorded and what a later
-    //    run compares against. The column is reported when it differs and otherwise ignored.
-    if (manifest.seq !== answer.seq)
-        out.serverSeqDisagreed = answer.seq;
-    // ⛔ THE VERSION THAT IS KEPT IS THE SEALED ONE, and so are the bytes it came out of. Believing
-    //    the server's column here would let it decide which copy this machine keeps.
-    writeSeen(accountId, manifest.seq, fp, answer.ct);
-    return out;
 }

package/dist/mark-render.d.ts

@@ -0,0 +1,26 @@
+import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+/** The three marks, in the shape `ls --json` prints and `markSuffix` draws. */
+export interface EntryMarks {
+    /** Starred: shown in the drive's favourites as well as in the folder the file lives in. */
+    favorite: boolean;
+    /** Held at the top of its own folder's listing, whatever the sort says. */
+    pinned: boolean;
+    /** The person's own labels for this entry, as text. Empty when it wears none. */
+    labels: readonly string[];
+}
+/**
+ * The marks on one entry — always all three.
+ *
+ * ⚠ ABSENT IS `false` HERE AND ABSENCE IN THE LIST, and the difference is deliberate. The format
+ *   writes a mark only when it is on, because the whole list is re-sealed on every change and
+ *   re-downloaded on every cold start. A reader parsing this needs the opposite: a field that is
+ *   always there, so "this file is not starred" cannot be mistaken for "this output does not say".
+ */
+export declare function marksOf(entry: ManifestEntry): EntryMarks;
+/**
+ * What `ls` puts after a row, or an empty string when the entry wears no mark.
+ *
+ * ⚠ It carries its own leading spaces, exactly like the trash suffix beside it, so a row with no
+ *   marks is byte-for-byte the row that was printed before marks existed.
+ */
+export declare function markSuffix(marks: EntryMarks): string;

package/dist/mcp-args.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keywords a schema uses that this checker does not enforce.
+ *
+ * ⛔ THE POINT IS THAT IT IS NOT EMPTY-BY-ASSUMPTION. A checker that silently skips what it does
+ *    not understand still returns "no problems", and a schema that grew a `minimum` or a `oneOf`
+ *    would go on being advertised while nothing held it. A test compares this against the real
+ *    tool table, so growing a schema past this file turns something red.
+ */
+export declare function unsupported(schema: unknown): string[];
+/**
+ * Compare one call's arguments against the schema its tool advertised.
+ *
+ * Returns the problems, most important first: a missing required argument before a wrong type,
+ * because a caller that forgot one is usually about to be told about the other for the same reason.
+ * An empty array means the call may proceed.
+ */
+export declare function checkArgs(schema: unknown, args: unknown): string[];

package/dist/mcp-ask.d.ts

@@ -0,0 +1,43 @@
+/** What came back, once the three protocol actions are read for what they mean here. */
+export type AskOutcome = 
+/** The person said yes. */
+"yes"
+/** The person said no, or dismissed the question without answering. Both mean: do not proceed. */
+ | "no"
+/** There was nobody to ask — the client never said it could. */
+ | "unreachable";
+/** Sends one JSON-RPC request to the client and resolves with whatever comes back as its result. */
+export type SendRequest = (method: string, params: Record<string, unknown>) => Promise<unknown>;
+/**
+ * The question this server asks, in one place so that every caller asks it the same way.
+ *
+ * ⛔ ONE BOOLEAN, NOT A FREE-TEXT FIELD. A client renders this schema into whatever it renders it
+ *    into, and a checkbox somebody has to tick is the shape that survives every rendering. A text
+ *    field would let a client accept "no" as a filled-in answer.
+ */
+export declare const CONFIRM_SCHEMA: Readonly<Record<string, unknown>>;
+/**
+ * Read an `elicitation/create` result. Pure, so the three actions can be tested without a pipe.
+ *
+ * ⛔ ONLY `accept` WITH `confirm === true` IS A YES. `decline` and `cancel` are both no — the
+ *    specification distinguishes "refused" from "dismissed" so that a server can offer something
+ *    else, and here there is nothing else to offer. An `accept` carrying no content, or content
+ *    with the box unticked, is a no as well: the person was shown the question and did not agree.
+ *
+ * ⛔ ANYTHING UNRECOGNISED IS A NO. A malformed answer is not an answer, and the direction to fail
+ *    in is the one where a file is not handed to somebody.
+ */
+export declare function readAnswer(result: unknown): AskOutcome;
+/** Whether the client said, at `initialize`, that it can put a question in front of a person. */
+export declare function declaredElicitation(capabilities: unknown): boolean;
+/** How a session asks, or `null` when this session has no way to ask at all. */
+export type Asker = ((message: string) => Promise<AskOutcome>) | null;
+/**
+ * Build the asker for a session.
+ *
+ * ⛔ THE CAPABILITY IS READ ONCE, FROM `initialize`, AND NEVER GUESSED AFTERWARDS. A client that
+ *    did not declare elicitation is not sent one: the specification says a server may only use a
+ *    capability the other side declared, and a request it does not understand is at best an error
+ *    on the wire and at worst a hung tool call waiting for an answer that is never coming.
+ */
+export declare function askerFor(capabilities: unknown, send: SendRequest): Asker;