@vecteur/cli 0.3.0 → 0.4.0

package/src/client.js

@@ -1,6 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
 
-import { EVENT_KINDS, validateAdmitted, validateProject, validateRunAck } from "./contract.js";
+import {
+  ARTIFACT_MEDIA_TYPES, EVENT_KINDS, OWNER_CONTRACT_IDENTITY, validateAdmitted,
+  validateCustomerCostProjection, validateDeviceAuthorization, validateLimitDenial,
+  validatePatCreated, validateProject, validateRunAck, validateAccount, validateQuotaDenial,
+  RECOVERY_ACTIONS,
+} from "./contract.js";
 import { readCredentials } from "./credentials.js";
 import { CliError } from "./errors.js";
 import { canonicalJson } from "./format.js";
@@ -9,12 +14,15 @@ import { canonicalJson } from "./format.js";
 export { CliError };
 
 const DEFAULT_TIMEOUT_MS = 120_000;
+export const DEFAULT_ORIGIN = "https://vecteur.space";
 const TOKEN_PATTERN = /vct_[A-Za-z0-9_-]{20,}/g;
+const TOKEN_SHAPE = /^vct_[A-Za-z0-9_-]{43}$/;
 const RELEASE_TIMEOUT = Symbol("release-timeout");
 const RESPONSE_ACTIVITY = Symbol("response-activity");
 const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 const MAX_FRAME_BYTES = 1024 * 1024;
 const MAX_EVENTS = 10_000;
+const CAS_REF_SHAPE = /^sha256:([0-9a-f]{64})$/;
 
 
 export function redact(value) {
@@ -28,57 +36,128 @@ function refuseSecretValue(value) {
   return value;
 }
 
+function canonicalOrigin(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new CliError("origin_invalid", "origin must be an absolute public origin");
+  }
+  const lexicalLoopback = /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d{1,5})?$/.test(raw);
+  if ((url.protocol !== "https:" && !lexicalLoopback) ||
+      url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new CliError("origin_invalid", "origin must be HTTPS or an exact loopback HTTP origin");
+  }
+  return url.origin;
+}
+
+function originKey(raw) {
+  const stripped = String(raw).replace(/\/+$/, "");
+  try { return new URL(stripped).origin; } catch { return stripped; }
+}
+
 /**
- * Where a run gets its origin and its token, in one place, with the environment winning.
+ * Where a run gets its origin and its token, in one place.
  *
- * The environment first, because that is how CI and a container pass a credential and neither
- * should have to write a file to do it. The stored login second, so a human logs in once —
- * SRD 06's release bar for this door is "one persistent login, the same product from any
- * working directory", and reading only the environment made "logged in" last one shell.
+ * Origin precedence is `--origin` > `VECTEUR_BASE_URL` > the store's current origin. The
+ * environment token still wins, because that is how CI and a container pass a credential
+ * and neither should have to write a file to do it. `VECTEUR_TOKEN` is the CI path and is
+ * never written or cleared by login or logout.
  *
- * Both are all-or-nothing per field: a stored login does not lend its token to an environment
- * that names a different origin, because a token minted for one deployment silently pointed at
- * another is a credential leak with a good explanation.
+ * A stored login does not lend its token to a different origin named by `--origin` or
+ * `VECTEUR_BASE_URL`: a token minted for one deployment silently pointed at another is a
+ * credential leak with a good explanation.
  */
-export function configuration(env = process.env, stored = undefined) {
-  const saved = stored === undefined ? readCredentials(env) : stored;
-  const token = env.VECTEUR_TOKEN ?? saved?.token ?? "";
+/**
+ * The one origin rule: `--origin` > `VECTEUR_BASE_URL` > the store's current origin > the
+ * public product. `login` resolved it separately and reached a different answer on an empty
+ * machine — it fell back to the product, `configuration` fell back to the empty string — which
+ * is what two owners of one rule always eventually do.
+ */
+export function resolveOrigin(env = process.env, stored = undefined, originFlag = undefined) {
+  const saved = stored === undefined && !env.VECTEUR_TOKEN ? readCredentials(env) : stored;
+  return canonicalOrigin(
+    originFlag ?? env.VECTEUR_BASE_URL ?? saved?.current ?? DEFAULT_ORIGIN);
+}
+
+/** The one timeout rule, so a bound the client enforces is not re-stated by its caller. */
+export function requestTimeout(env = process.env) {
+  const timeout = Number(env.VECTEUR_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS);
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 120_000) {
+    throw new CliError("timeout_invalid", "VECTEUR_TIMEOUT_MS must be 100 to 120000");
+  }
+  return timeout;
+}
+
+/** The one token-shape rule, so `login` and `configuration` cannot disagree about a credential. */
+export function isTokenShaped(value) {
+  return TOKEN_SHAPE.test(value);
+}
+
+export function configuration(env = process.env, stored = undefined, originFlag = undefined) {
+  // THE CI PATH DOES NOT READ THE STORE. `VECTEUR_TOKEN` is how a container and a CI job hand
+  // over a credential, and neither has a store; reading one anyway meant an unreadable file on
+  // the machine broke a run that never needed it — `credentials_unreadable` for a credential
+  // the environment had already supplied.
+  const saved = env.VECTEUR_TOKEN
+    ? null
+    : (stored === undefined ? readCredentials(env) : stored);
+  const named = originFlag ?? env.VECTEUR_BASE_URL;
 
   // A STORED TOKEN GOES TO THE ORIGIN IT WAS STORED FOR, AND NOWHERE ELSE.
-  //
-  // The two sources resolve field by field, which on its own lets `VECTEUR_BASE_URL=<other>`
-  // borrow the stored token and send it somewhere it was never minted for — a credential leak
-  // with a plausible explanation, and one a user would never see happen. If the environment
-  // names an origin, it must bring its own token.
-  if (!env.VECTEUR_TOKEN && saved && env.VECTEUR_BASE_URL &&
-      env.VECTEUR_BASE_URL.replace(/\/+$/, "") !== saved.origin) {
+  if (!env.VECTEUR_TOKEN && saved && named && !Object.hasOwn(saved.logins, originKey(named))) {
     throw new CliError("origin_mismatch",
-      `the stored login is for ${saved.origin} and VECTEUR_BASE_URL names `
-      + `${env.VECTEUR_BASE_URL} — set VECTEUR_TOKEN for that origin, or log in to it`);
+      `the stored login is for ${saved.current} and ${originFlag !== undefined ? "--origin" : "VECTEUR_BASE_URL"} names `
+      + `${named} — set VECTEUR_TOKEN for that origin, or log in to it`);
   }
 
-  if (!/^vct_[A-Za-z0-9_-]{43}$/.test(token)) {
+  const origin = resolveOrigin(env, saved, originFlag);
+  const token = env.VECTEUR_TOKEN ?? saved?.logins?.[originKey(origin)]?.token ?? "";
+
+  if (!isTokenShaped(token)) {
     throw new CliError("token_invalid", saved
       ? "the stored login does not hold one personal access token — run `vecteur login` again"
-      : "no login found: run `vecteur login --url <origin>`, or set VECTEUR_TOKEN");
+      : "no login found: run `vecteur login`, or set VECTEUR_TOKEN");
   }
-  const raw = env.VECTEUR_BASE_URL ?? saved?.origin ?? "";
-  let url;
-  try {
-    url = new URL(raw);
-  } catch {
-    throw new CliError("origin_invalid", "VECTEUR_BASE_URL must be an absolute public origin");
-  }
-  const lexicalLoopback = /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d{1,5})?$/.test(raw);
-  if ((url.protocol !== "https:" && !lexicalLoopback) ||
-      url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
-    throw new CliError("origin_invalid", "VECTEUR_BASE_URL must be HTTPS or an exact loopback HTTP origin");
+  return { origin, token, timeout: requestTimeout(env),
+    projectId: saved?.logins?.[originKey(origin)]?.project_id };
+}
+
+export function shouldOpenBrowser(noBrowser, env = process.env) {
+  if (noBrowser) return false;
+  if (process.platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY) return false;
+  return true;
+}
+
+export function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForDeviceAuthorization(client, grant, { sleep = delay, now = Date.now } = {}) {
+  if (!validateDeviceAuthorization(grant)) {
+    throw new CliError("device_authorization_invalid", "Server returned malformed owner data");
   }
-  const timeout = Number(env.VECTEUR_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS);
-  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 120_000) {
-    throw new CliError("timeout_invalid", "VECTEUR_TIMEOUT_MS must be 100 to 120000");
+  const intervalMs = grant.interval * 1000;
+  while (true) {
+    if (now() >= grant.expires_at * 1000) {
+      throw new CliError("device_expired", "This code has expired");
+    }
+    try {
+      const polled = await client.devicePoll(grant.device_code);
+      if (validatePatCreated(polled)) return polled;
+      if (polled && polled.status === "authorization_pending") {
+        await sleep(intervalMs);
+        continue;
+      }
+      throw new CliError("device_poll_invalid", "Server returned malformed owner data");
+    } catch (error) {
+      if (error instanceof CliError && error.code === "device_slow_down") {
+        await sleep(intervalMs);
+        continue;
+      }
+      throw error;
+    }
   }
-  return { origin: url.origin, token, timeout };
 }
 
 function exactObject(value, fields, code) {
@@ -231,7 +310,8 @@ export class VecteurClient {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          Authorization: `Bearer ${this.config.token}`,
+          "X-Vecteur-Client": OWNER_CONTRACT_IDENTITY,
+          ...(this.config.token ? { Authorization: `Bearer ${this.config.token}` } : {}),
           ...(body === undefined ? {} : { "Content-Type": "application/json" }),
           ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
           ...(accept ? { Accept: accept } : {}),
@@ -247,20 +327,84 @@ export class VecteurClient {
         signal?.removeEventListener("abort", cancel);
         clearTimeout(overallTimer); clearTimeout(idleTimer);
       };
+      if (response.headers.get("X-Vecteur-Contract") === null) {
+        throw new CliError(
+          "origin_not_vecteur",
+          `origin ${this.config.origin}; cause=missing_vecteur_contract; next: pass the Vecteur origin with --origin`,
+        );
+      }
       if (response.status >= 300 && response.status < 400) {
         throw new CliError("redirect_refused", "Public API redirects are refused");
       }
       if (!response.ok) {
         let code = `http_${response.status}`;
+        let ownerMessage = "";
+        let refused = null;
         try {
-          const candidate = parseOwnerJson(await boundedText(response)).error?.code;
-          if (typeof candidate === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(candidate)) {
-            code = candidate;
+          // THE GUARD RUNS ON REFUSALS TOO. It sat on the success path alone, so a 401 whose
+          // body carried `vct_…` was read for its `error.code` and reported as `pat_revoked`:
+          // the one exception to the guard is an HTTP 201 from the device poll, and an error
+          // is not it. A credential in a refusal is still a credential the door leaked.
+          const body = refuseSecretValue(parseOwnerJson(await boundedText(response)));
+          const error = body.error;
+          if (error && typeof error === "object" && !Array.isArray(error)) {
+            const candidate = error.code;
+            if (typeof candidate === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(candidate)) {
+              code = candidate;
+            }
+            if (candidate === "project_quota_exhausted") {
+              if (!validateQuotaDenial(error.quota) || typeof error.message !== "string"
+                  || !error.message.length || /[\r\n\0]/.test(error.message)) {
+                throw new CliError("quota_invalid", "Server returned malformed Project quota data");
+              }
+              const actions = error.quota.recovery.map(id => {
+                if (!Object.hasOwn(RECOVERY_ACTIONS, id) || !RECOVERY_ACTIONS[id].href) {
+                  throw new CliError("recovery_action_invalid", `Unknown Project recovery action: ${id}`);
+                }
+                const action = RECOVERY_ACTIONS[id];
+                return `${action.label}: ${new URL(action.href, this.config.origin).href}`;
+              });
+              const quota = error.quota;
+              ownerMessage = `${error.message}; ${quota.current} of ${quota.maximum} active projects used on the ${quota.tier} plan`
+                + (actions.length ? `; next: ${actions.join("; ")}` : "");
+            }
+            if (candidate === "customer_cost_exhausted") {
+              if (!validateLimitDenial(error.limit)) {
+                throw new CliError("customer_cost_invalid", "Server returned malformed customer-cost refusal");
+              }
+              const limit = error.limit;
+              const binding = `${limit.binding_scope.kind}:${limit.binding_scope.scope.type}:${limit.binding_scope.scope.id}`;
+              const reset = new Date(limit.reset_at * 1000).toISOString().replace(".000Z", "Z");
+              ownerMessage = `Customer cost limit reached; binding=${binding}; reset=${reset} UTC; next=${limit.recovery.join(",")}`;
+            }
+            if (["pat_expired", "pat_invalid", "pat_revoked"].includes(candidate)) {
+              ownerMessage = "credential is expired or revoked; next: vecteur login";
+            }
+            if (candidate === "pat_ancestry_inactive") {
+              ownerMessage = "seat or Organization is inactive; next: contact your Organization owner or Vecteur support";
+            }
+            if (
+              candidate === "client_outdated"
+              && Object.keys(error).sort().join("\n") === "code\nmessage"
+              && typeof error.message === "string"
+              && error.message.length > 0
+              && error.message.length <= 512
+              && !/[\r\n\0]/.test(error.message)
+            ) {
+              try { ownerMessage = refuseSecretValue(error.message); } catch {}
+            }
           }
         } catch (error) {
           if (error?.name === "AbortError") throw error;
+          if (error instanceof CliError && [
+            "secret_response_refused", "quota_invalid", "recovery_action_invalid", "customer_cost_invalid",
+          ].includes(error.code)) refused = error;
         }
-        throw new CliError(code, `Public API refused request with HTTP ${response.status}`);
+        if (refused) throw refused;
+        throw new CliError(
+          code,
+          ownerMessage || `Public API refused request with HTTP ${response.status}`,
+        );
       }
       return response;
     } catch (error) {
@@ -268,13 +412,33 @@ export class VecteurClient {
       clearTimeout(overallTimer); clearTimeout(idleTimer);
       if (error?.name === "AbortError") {
         if (signal?.aborted) throw new CliError("request_cancelled", "Public API request was cancelled");
-        throw new CliError("request_timeout", "Public API request timed out");
+        throw new CliError("request_timeout",
+          `origin ${this.config.origin}; cause=timeout; next: check the network and retry`);
       }
       if (error instanceof CliError) throw error;
-      throw new CliError("request_failed", "Public API request failed");
+      throw new CliError("request_failed",
+        `origin ${this.config.origin}; cause=transport; next: check the network and --origin`);
     }
   }
 
+  async projectList(signal = undefined) {
+    const value = await this.#json("GET", "/api/projects", { signal });
+    if (!Array.isArray(value) || !value.every(validateProject)) {
+      throw new CliError("projects_invalid", "Server returned malformed Project list");
+    }
+    return value;
+  }
+
+  async projectCreate(name, workspaceId, signal = undefined) {
+    const value = await this.#json("POST", "/api/projects", {
+      body: { name, workspace_id: workspaceId }, signal,
+    });
+    if (!validateProject(value) || value.workspace_id !== workspaceId) {
+      throw new CliError("project_invalid", "Server returned malformed project data");
+    }
+    return value;
+  }
+
   async projectGet(projectId, signal = undefined) {
     const value = await this.#json("GET", `/api/projects/${encodeURIComponent(projectId)}`, { signal });
     if (!validateProject(value) || value.id !== projectId) {
@@ -283,6 +447,86 @@ export class VecteurClient {
     return value;
   }
 
+  async deviceMint(signal = undefined) {
+    const value = await this.#json("POST", "/api/auth/device", { body: {}, signal });
+    if (!validateDeviceAuthorization(value)) {
+      throw new CliError("device_authorization_invalid", "Server returned malformed owner data");
+    }
+    return value;
+  }
+
+  async devicePoll(deviceCode, signal = undefined) {
+    return this.#json("POST", "/api/auth/device/poll", { body: { device_code: deviceCode }, signal });
+  }
+
+  async accountMe(signal = undefined) {
+    const value = await this.#json("GET", "/api/auth/me", { signal });
+    if (!validateAccount(value)) throw new CliError("account_invalid", "Server returned malformed owner data");
+    return value;
+  }
+
+  async credentialSelfRevoke(signal = undefined) {
+    return this.#json("DELETE", "/api/credentials/self", { signal });
+  }
+
+  async customerCost(projectId, signal = undefined) {
+    const query = new URLSearchParams({ scope: "project", scope_id: projectId, period: "utc_month" });
+    const value = await this.#json("GET", `/api/customer-cost?${query}`, { signal });
+    if (!validateCustomerCostProjection(value) || value.scope.type !== "project"
+        || value.scope.id !== projectId) {
+      throw new CliError("customer_cost_invalid", "Server returned malformed customer-cost projection");
+    }
+    return value;
+  }
+
+  async artifactGet(casRef, projectId, onChunk, signal = undefined) {
+    const identity = CAS_REF_SHAPE.exec(casRef);
+    if (!identity || typeof projectId !== "string" || !projectId
+        || typeof onChunk !== "function") {
+      throw new CliError("artifact_invalid", "artifact get requires an admitted sha256 CAS id and Project");
+    }
+    const query = new URLSearchParams({ project_id: projectId });
+    const response = await this.request(
+      "GET", `/api/artifacts/${encodeURIComponent(casRef)}?${query}`, { signal },
+    );
+    try {
+      const contentType = response.headers.get("content-type");
+      if (!Object.values(ARTIFACT_MEDIA_TYPES).includes(contentType)) {
+        throw new CliError("artifact_invalid", "Server returned an undeclared artifact media type");
+      }
+      const declared = response.headers.get("content-length");
+      if (declared === null || !/^(?:0|[1-9][0-9]*)$/.test(declared)
+          || !Number.isSafeInteger(Number(declared))) {
+        throw new CliError("artifact_invalid", "Server returned an invalid artifact length");
+      }
+      if (!response.body) throw new CliError("artifact_invalid", "Server returned no artifact bytes");
+      const digest = createHash("sha256");
+      let bytes = 0;
+      for await (const chunk of response.body) {
+        response[RESPONSE_ACTIVITY]?.();
+        bytes += chunk.byteLength;
+        if (bytes > Number(declared)) {
+          throw new CliError("artifact_invalid", "Artifact bytes exceed the declared length");
+        }
+        digest.update(chunk);
+        await onChunk(chunk);
+      }
+      if (bytes !== Number(declared)) {
+        throw new CliError("artifact_invalid", "Artifact bytes differ from the declared length");
+      }
+      if (digest.digest("hex") !== identity[1]) {
+        throw new CliError("artifact_invalid", "Artifact bytes differ from the admitted digest");
+      }
+      return { cas_ref: casRef, project_id: projectId, content_type: contentType, bytes };
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw new CliError("request_failed",
+        `origin ${this.config.origin}; cause=artifact_transport; next: check the network and retry`);
+    } finally {
+      response[RELEASE_TIMEOUT]?.();
+    }
+  }
+
   async runSubmit(projectId, ask, onEvent = null, signal = undefined) {
     const value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/runs`, {
       body: { ask, attachments: [], parent_state_hash: null, ui_context: null },
@@ -292,7 +536,15 @@ export class VecteurClient {
     if (!validateRunAck(value)) {
       throw new CliError("run_ack_invalid", "Server returned malformed run acknowledgement");
     }
-    return this.runEvents(value.run_id, onEvent, signal);
+    try {
+      return await this.runEvents(value.run_id, onEvent, signal);
+    } catch (error) {
+      if (error instanceof CliError && error.code === "pat_expired") {
+        throw new CliError("pat_expired",
+          `credential expired after Run ${value.run_id} was admitted; next: vecteur login; then: vecteur run get ${value.run_id}`);
+      }
+      throw error;
+    }
   }
 
   async runGet(runId, signal = undefined) {
@@ -318,7 +570,8 @@ export class VecteurClient {
       events = await parseSse(response, runId, onEvent);
     } catch (error) {
       if (error?.name === "AbortError") {
-        throw new CliError("request_timeout", "Public API request timed out");
+        throw new CliError("request_timeout",
+          `origin ${this.config.origin}; cause=timeout; next: check the network and retry`);
       }
       throw error;
     } finally {
@@ -344,7 +597,19 @@ export class VecteurClient {
       if (response.headers.get("content-type")?.split(";", 1)[0] !== "application/json") {
         throw new CliError("response_invalid", "Public API response is not JSON");
       }
-      try { return refuseSecretValue(parseOwnerJson(await boundedText(response))); }
+      try {
+        const value = parseOwnerJson(await boundedText(response));
+        // Sole exception to refuseSecretValue: HTTP 201 from POST /api/auth/device/poll,
+        // accepted only after exact validation of the owner PatCreated shape. Pending
+        // polls, every other status and every other route keep the guard.
+        if (method === "POST" && path === "/api/auth/device/poll" && response.status === 201) {
+          if (!validatePatCreated(value)) {
+            throw new CliError("pat_created_invalid", "Server returned malformed owner data");
+          }
+          return value;
+        }
+        return refuseSecretValue(value);
+      }
       catch (error) {
         if (error?.name === "AbortError") {
           throw new CliError("request_timeout", "Public API request timed out");

package/src/contract.js

@@ -1,12 +1,47 @@
 // GENERATED by scripts/gen-contract.mjs from owner TypeScript projections.
-export const OWNER_CONTRACT_SHA256 = "a8a1bfec596231c560f80e9f9dbbc38f4b9dff0eef7e87db5bc4687f98b89597";
-export const EVENT_KINDS = Object.freeze(["source","step_started","step_finished","synthesis","artifact","cta","state_advanced","terminal","heartbeat","assistant_delta","step_label","context_frame","knowledge_binding","engineering_projection"]);
-export const ORIGIN_KINDS = Object.freeze(["user","hypothesis","derived","file","catalog","default"]);
-export const ORIGIN_WORD = Object.freeze({"user":"your brief","hypothesis":"assumed","derived":"derived","file":"your file","catalog":"catalogue","default":"default","unattributed":"unstated"});
-const exact=(v,k)=>!!v&&typeof v==="object"&&!Array.isArray(v)&&Object.keys(v).sort().join("\n")===[...k].sort().join("\n");
+export const OWNER_CONTRACT_IDENTITY = "api-sha256:f51b0fce34f18d782dbc403d177cab30b03ad4506c8453d8aaa106af476053a9;run-wire-sha256:3a9467e54836696b554ffa163decf62704323ea8943f57857c6d719cf8d88674";
+export const RECOVERY_ACTIONS = Object.freeze({"delete_project":{"label":"Delete a project","href":"/projects"},"upgrade_plan":{"label":"Upgrade your plan","href":"/dashboard/billing"},"wait_for_reset":{"label":"Wait until the UTC reset","href":null}});
+export const EVENT_KINDS = Object.freeze(["source","step_started","step_finished","synthesis","artifact","cta","state_advanced","terminal","heartbeat","assistant_delta","step_label","context_frame","knowledge_binding","engineering_projection","provider_attempt","clarification"]);
+export const TERMINAL_FIELDS = Object.freeze(["answer","defect","evidence_dag","instruction_source","intent","missing_input_need","missing_inputs","provider_retry_offer","recovery","state","steps"]);
+export const ARTIFACT_MEDIA_TYPES = Object.freeze({"code":"text/plain","csv":"text/csv","docx":"application/vnd.openxmlformats-officedocument.wordprocessingml.document","drive":"application/vnd.google-drive","html":"text/html","md":"text/markdown","pdf":"application/pdf","xlsx":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"});
+export const TERMINAL_RECOVERY_DECLARATIONS = Object.freeze({"artifact_publication_missing":[["start_run",["project_id"]]],"artifact_store_unavailable":[["start_run",["project_id"]]],"budget_exhausted":[["start_run",["project_id"]]],"cancelled":[["start_run",["project_id"]]],"cause_unrecorded":[["start_run",["project_id"]]],"clarification_custody_invalid":[["start_run",["project_id"]]],"clarification_custody_lost":[["start_run",["project_id"]]],"clarification_resume_invalid":[["start_run",["project_id"]]],"clarification_unpersisted":[["start_run",["project_id"]]],"context_unselected":[["start_run",["project_id"]]],"credential_class_disclosure":[["start_run",["project_id"]]],"design_state_missing":[["start_run",["project_id"]]],"evidence_admission_invalid":[["start_run",["project_id"]]],"evidence_artifact_invalid":[["start_run",["project_id"]]],"evidence_artifact_unbound":[["start_run",["project_id"]]],"evidence_binding_unresolved":[["start_run",["project_id"]]],"evidence_context_invalid":[["start_run",["project_id"]]],"evidence_extract_unreached":[["start_run",["project_id"]]],"evidence_missing":[["start_run",["project_id"]]],"evidence_owner_receipt_mismatch":[["start_run",["project_id"]]],"evidence_owner_receipt_missing":[["start_run",["project_id"]]],"evidence_payload_invalid":[["start_run",["project_id"]]],"evidence_reached_invalid":[["start_run",["project_id"]]],"evidence_replay_invalid":[["start_run",["project_id"]]],"evidence_run_mismatch":[["start_run",["project_id"]]],"evidence_seal_collision":[["start_run",["project_id"]]],"evidence_selected_unreached":[["start_run",["project_id"]]],"execution_route_invalid":[["start_run",["project_id"]]],"executor_root_invalid":[["start_run",["project_id"]]],"extraction_offer_invalid":[["start_run",["project_id"]]],"extraction_offer_tampered":[["start_run",["project_id"]]],"fact_support_unread":[["start_run",["project_id"]]],"harness_arm_invalid":[["start_run",["project_id"]]],"harness_event_unmapped":[["start_run",["project_id"]]],"harness_exited":[["start_run",["project_id"]]],"harness_mapping_failed":[["start_run",["project_id"]]],"harness_session_invalid":[["start_run",["project_id"]]],"harness_session_missing":[["start_run",["project_id"]]],"harness_timeout":[["start_run",["project_id"]]],"lease_interval_invalid":[["start_run",["project_id"]]],"ledger_malformed":[["start_run",["project_id"]]],"max_tokens":[["start_run",["project_id"]]],"profile_eligibility_changed":[["start_run",["project_id"]]],"prompt_provenance_unavailable":[["start_run",["project_id"]]],"provider_budget_exhausted":[["start_run",["project_id"]]],"provider_budget_missing":[["start_run",["project_id"]]],"provider_budget_unavailable":[["start_run",["project_id"]]],"provider_relay_absent":[["start_run",["project_id"]]],"provider_route_control_invalid":[["start_run",["project_id"]]],"provider_route_exhausted":[["start_run",["project_id"]],["retry_run",["source_run_id","offer_id","generation"]]],"provider_route_failure_unobserved":[["start_run",["project_id"]]],"provider_route_reconciliation_invalid":[["start_run",["project_id"]]],"provider_route_restart_terminal":[["start_run",["project_id"]]],"provider_training_opted_in":[["start_run",["project_id"]]],"publish_seal_missing":[["start_run",["project_id"]]],"replay_capture_digest_mismatch":[["start_run",["project_id"]]],"replay_capture_invalid":[["start_run",["project_id"]]],"replay_config_incomplete":[["start_run",["project_id"]]],"replay_failed":[["start_run",["project_id"]]],"replay_no_requests":[["start_run",["project_id"]]],"replay_patch_invalid":[["start_run",["project_id"]]],"replay_plugin_absent":[["start_run",["project_id"]]],"replay_provider_socket":[["start_run",["project_id"]]],"replay_receipt_invalid":[["start_run",["project_id"]]],"replay_receipt_owner_chown":[["start_run",["project_id"]]],"replay_receipt_owner_incomplete":[["start_run",["project_id"]]],"replay_receipt_owner_invalid":[["start_run",["project_id"]]],"replay_request_observation_count":[["start_run",["project_id"]]],"replay_request_observation_invalid":[["start_run",["project_id"]]],"replay_request_observation_missing":[["start_run",["project_id"]]],"replay_request_owner_chown":[["start_run",["project_id"]]],"replay_socket_observation_invalid":[["start_run",["project_id"]]],"replay_socket_observation_missing":[["start_run",["project_id"]]],"replay_socket_owner_chown":[["start_run",["project_id"]]],"run_database_capability_refused":[["start_run",["project_id"]]],"runtime_unavailable":[["start_run",["project_id"]]],"sealed_contract_violated":[["start_run",["project_id"]]],"sealed_file_missing":[["start_run",["project_id"]]],"seat_patch_absent":[["start_run",["project_id"]]],"seat_patch_drift":[["start_run",["project_id"]]],"selection_admission_invalid":[["start_run",["project_id"]]],"selection_context_invalid":[["start_run",["project_id"]]],"selection_receipt_conflict":[["start_run",["project_id"]]],"selection_receipt_invalid":[["start_run",["project_id"]]],"selection_receipt_missing":[["start_run",["project_id"]]],"selection_required":[["start_run",["project_id"]]],"state_corrupt":[["start_run",["project_id"]]],"state_file_invalid":[["start_run",["project_id"]]],"state_invalid":[["start_run",["project_id"]]],"state_payload_overflow":[["start_run",["project_id"]]],"state_unencodable":[["start_run",["project_id"]]],"state_version_unknown":[["start_run",["project_id"]]],"usage_egress_mismatch":[["start_run",["project_id"]]]});
+export const ORIGIN_KINDS = Object.freeze(["user","hypothesis","derived","knowledge","file","catalog","default"]);
+export const ORIGIN_WORD = Object.freeze({"user":"your brief","hypothesis":"assumed","derived":"derived","knowledge":"Vecteur knowledge","file":"your file","catalog":"catalogue","default":"default","unattributed":"unstated"});
+const shape=(v,r,o=[])=>!!v&&typeof v==="object"&&!Array.isArray(v)&&r.every(k=>Object.hasOwn(v,k))&&Object.keys(v).every(k=>r.includes(k)||o.includes(k));
+const exact=(v,k)=>shape(v,k)&&Object.keys(v).length===k.length;
 const text=(v)=>typeof v==="string"&&v.length>0; const integer=(v)=>Number.isSafeInteger(v);
-const member=(v)=>exact(v,["user_id","email","display_name","role"])&&[v.user_id,v.email,v.display_name].every(text)&&["OWNER","ADMIN","EDITOR","VIEWER"].includes(v.role);
-export const validateProject=(v)=>exact(v,["id","name","org_id","workspace_id","role","role_source","members","created_at","updated_at"])&&[v.id,v.name,v.org_id,v.workspace_id].every(text)&&["OWNER","ADMIN","EDITOR","VIEWER"].includes(v.role)&&["workspace","project"].includes(v.role_source)&&Array.isArray(v.members)&&v.members.every(member)&&integer(v.created_at)&&integer(v.updated_at);
-export const validateRunAck=(v)=>exact(v,["run_id","state_hash","accepted_at","profile"])&&[v.run_id,v.state_hash,v.profile].every(text)&&integer(v.accepted_at);
-const usage=(v)=>exact(v,["state","provider","model_id","input_tokens","output_tokens","cost_usd"])&&["recorded","usage_unavailable"].includes(v.state)&&[v.provider,v.model_id].every(text)&&[v.input_tokens,v.output_tokens].every(x=>x===null||(integer(x)&&x>=0))&&(v.cost_usd===null||(typeof v.cost_usd==="number"&&Number.isFinite(v.cost_usd)&&v.cost_usd>=0));
-export const validateAdmitted=(v)=>exact(v,["run_id","state_hash","result_hash","profile","terminal","usage","events"])&&[v.run_id,v.state_hash,v.result_hash,v.profile].every(text)&&["ok","partial","blocked","refused","infeasible_physics","capability_gap"].includes(v.terminal)&&usage(v.usage)&&Array.isArray(v.events);
+const ownerAccount=v=>shape(v,["id","email","display_name","tier","org_id","organization_role","workspaces","connectors","capabilities","entitlements","avatar_url","display_currency","model_cost_estimates","is_platform_operator"],[])&&(typeof v.id==="string")&&(typeof v.email==="string")&&(typeof v.display_name==="string")&&(ownerTier(v.tier))&&(typeof v.org_id==="string")&&((v.organization_role==="OWNER"||v.organization_role==="ADMIN"||v.organization_role==="MEMBER"))&&(Array.isArray(v.workspaces)&&v.workspaces.every(x=>ownerWorkspace(x)))&&(Array.isArray(v.connectors)&&v.connectors.every(x=>typeof x==="string"))&&(Array.isArray(v.capabilities)&&v.capabilities.every(x=>ownerCapability(x)))&&(ownerEntitlements(v.entitlements))&&((typeof v.avatar_url==="string"||v.avatar_url===null))&&((v.display_currency==="EUR"||v.display_currency==="USD"))&&(ownerModelCostEstimates(v.model_cost_estimates))&&(typeof v.is_platform_operator==="boolean");
+const ownerTier=v=>(v==="free"||v==="pro"||v==="enterprise");
+const ownerWorkspace=v=>shape(v,["id","org_id","name","status"],[])&&(typeof v.id==="string")&&(typeof v.org_id==="string")&&(typeof v.name==="string")&&(v.status==="active");
+const ownerCapability=v=>shape(v,["id","affordance","state","required_tier","reason","recovery"],[])&&(typeof v.id==="string")&&((v.affordance==="composer-source"||v.affordance==="workspace-export"||v.affordance==="composer-preference"))&&((v.state==="available"||v.state==="locked"||v.state==="disconnected"||v.state==="unavailable"))&&((v.required_tier==="pro"||v.required_tier==="enterprise"||v.required_tier===null))&&(typeof v.reason==="string")&&((typeof v.recovery==="string"||v.recovery===null));
+const ownerEntitlements=v=>shape(v,["active_projects","seats"],[])&&(ownerActiveProjectEntitlement(v.active_projects))&&(ownerSeatEntitlement(v.seats));
+const ownerActiveProjectEntitlement=v=>shape(v,["resource","current","maximum","state","reason","recovery"],[])&&(v.resource==="active_projects")&&(Number.isFinite(v.current))&&((Number.isFinite(v.maximum)||v.maximum===null))&&((v.state==="available"||v.state==="locked"))&&(typeof v.reason==="string")&&(Array.isArray(v.recovery)&&v.recovery.every(x=>(x==="delete_project"||x==="upgrade_plan")));
+const ownerSeatEntitlement=v=>shape(v,["current","states","reason"],[])&&(Number.isFinite(v.current))&&(v.states!==null&&typeof v.states==="object"&&!Array.isArray(v.states)&&Object.values(v.states).every(x=>Number.isFinite(x)))&&(typeof v.reason==="string");
+const ownerModelCostEstimates=v=>shape(v,["schema","catalogue_envelope_sha256","reference_sha256","projection_sha256","workload","display_currency","rows","cost_ticks"],[])&&(v.schema==="vecteur.model-cost-estimates.v4")&&(typeof v.catalogue_envelope_sha256==="string")&&(typeof v.reference_sha256==="string")&&(typeof v.projection_sha256==="string")&&(typeof v.workload==="string")&&((v.display_currency==="EUR"||v.display_currency==="USD"))&&(Array.isArray(v.rows)&&v.rows.every(x=>ownerModelCostEstimate(x)))&&(Array.isArray(v.cost_ticks)&&v.cost_ticks.every(x=>ownerModelCostTick(x)));
+const ownerModelCostEstimate=v=>shape(v,["selection_id","customer_gross_microusd","display"],[])&&(typeof v.selection_id==="string")&&(Number.isFinite(v.customer_gross_microusd))&&(typeof v.display==="string");
+const ownerModelCostTick=v=>shape(v,["customer_gross_microusd","display"],[])&&(Number.isFinite(v.customer_gross_microusd))&&(typeof v.display==="string");
+const ownerQuotaDenial=v=>shape(v,["resource","current","maximum","tier","recovery"],[])&&(typeof v.resource==="string")&&(Number.isFinite(v.current))&&(Number.isFinite(v.maximum))&&(typeof v.tier==="string")&&(Array.isArray(v.recovery)&&v.recovery.every(x=>typeof x==="string"));
+const ownerCustomerCostProjection=v=>shape(v,["schema","scope","binding_scope","period_start","period_end","unit","used","limit","remaining","reset_at","coverage","display"],[])&&(v.schema==="vecteur.customer-cost-projection.v1")&&(ownerCostScope(v.scope))&&(ownerCostBindingScope(v.binding_scope))&&(Number.isFinite(v.period_start))&&(Number.isFinite(v.period_end))&&(v.unit==="customer_gross_microusd")&&((Number.isFinite(v.used)||v.used===null))&&((Number.isFinite(v.limit)||v.limit===null))&&((Number.isFinite(v.remaining)||v.remaining===null))&&(Number.isFinite(v.reset_at))&&((v.coverage==="complete"||v.coverage==="incomplete"))&&(ownerCustomerCostDisplay(v.display));
+const ownerCostScope=v=>shape(v,["type","id"],[])&&((v.type==="organization"||v.type==="workspace"||v.type==="project"||v.type==="user"))&&(typeof v.id==="string");
+const ownerCostBindingScope=v=>shape(v,["kind","scope"],[])&&((v.kind==="platform_tier"||v.kind==="restriction"||v.kind==="unlimited"))&&(ownerCostScope(v.scope));
+const ownerCustomerCostDisplay=v=>shape(v,["currency","used","limit","remaining"],[])&&((v.currency==="EUR"||v.currency==="USD"))&&((typeof v.used==="string"||v.used===null))&&((typeof v.limit==="string"||v.limit===null))&&((typeof v.remaining==="string"||v.remaining===null));
+const ownerLimitDenial=v=>shape(v,["schema","scope","binding_scope","period_start","period_end","unit","used","limit","remaining","reset_at","coverage","display","dimension","recovery"],[])&&(v.schema==="vecteur.customer-cost-projection.v1")&&(ownerCostScope(v.scope))&&(ownerCostBindingScope(v.binding_scope))&&(Number.isFinite(v.period_start))&&(Number.isFinite(v.period_end))&&(v.unit==="customer_gross_microusd")&&((Number.isFinite(v.used)||v.used===null))&&((Number.isFinite(v.limit)||v.limit===null))&&((Number.isFinite(v.remaining)||v.remaining===null))&&(Number.isFinite(v.reset_at))&&((v.coverage==="complete"||v.coverage==="incomplete"))&&(ownerCustomerCostDisplay(v.display))&&(v.dimension==="customer_cost")&&(Array.isArray(v.recovery)&&v.recovery.every(x=>(x==="wait_for_reset"||x==="upgrade_plan")));
+const ownerArtifact=v=>shape(v,["id","kind","cas_ref","filename"],["produced_by_step","from_input_rows","build_receipt_id","output_index"])&&(typeof v.id==="string")&&((v.kind==="docx"||v.kind==="xlsx"||v.kind==="pdf"||v.kind==="md"||v.kind==="csv"||v.kind==="html"||v.kind==="code"||v.kind==="drive"))&&(ownerCasRef(v.cas_ref))&&(typeof v.filename==="string")&&(v.produced_by_step===undefined||(typeof v.produced_by_step==="string"||v.produced_by_step===null))&&(v.from_input_rows===undefined||(Array.isArray(v.from_input_rows)&&v.from_input_rows.every(x=>typeof x==="string")||v.from_input_rows===null))&&(v.build_receipt_id===undefined||(typeof v.build_receipt_id==="string"||v.build_receipt_id===null))&&(v.output_index===undefined||(Number.isFinite(v.output_index)||v.output_index===null));
+const ownerCasRef=v=>typeof v==="string";
+const ownerSynthesis=v=>shape(v,["answer","core","terminal"],[])&&(typeof v.answer==="string")&&(v.core!==null&&typeof v.core==="object"&&!Array.isArray(v.core)&&Object.values(v.core).every(x=>true))&&((v.terminal==="ok"||v.terminal==="partial"||v.terminal==="blocked"||v.terminal==="refused"||v.terminal==="infeasible_physics"||v.terminal==="capability_gap"));
+export const validateAccount=v=>ownerAccount(v)&&[v.id,v.email,v.display_name,v.org_id].every(text)&&v.workspaces.every(w=>[w.id,w.org_id,w.name].every(text))&&integer(v.entitlements.active_projects.current)&&v.entitlements.active_projects.current>=0&&(v.entitlements.active_projects.maximum===null||(integer(v.entitlements.active_projects.maximum)&&v.entitlements.active_projects.maximum>=0));
+export const validateQuotaDenial=v=>ownerQuotaDenial(v)&&v.resource==="active_projects"&&integer(v.current)&&v.current>=0&&integer(v.maximum)&&v.maximum>=0&&text(v.tier);
+const plainText=v=>text(v)&&!/[\u0000-\u001f\u007f-\u009f]/.test(v); const costText=v=>v===null||plainText(v); const money=v=>v===null||(integer(v)&&v>=0);
+const costProjection=v=>[v.scope?.id,v.binding_scope?.scope?.id].every(plainText)&&[v.period_start,v.period_end,v.reset_at].every(x=>integer(x)&&x>=0&&x<=8640000000000)&&v.period_start<v.period_end&&v.reset_at===v.period_end&&[v.used,v.limit,v.remaining].every(money)&&[v.display?.used,v.display?.limit,v.display?.remaining].every(costText)&&(v.coverage==="complete"?(v.used!==null&&v.display.used!==null&&((v.limit===null&&v.remaining===null&&v.display.limit===null&&v.display.remaining===null)||(v.limit!==null&&v.remaining!==null&&v.display.limit!==null&&v.display.remaining!==null))):(v.used===null&&v.limit===null&&v.remaining===null&&v.display.used===null&&v.display.limit===null&&v.display.remaining===null));
+export const validateCustomerCostProjection=v=>ownerCustomerCostProjection(v)&&costProjection(v);
+export const validateLimitDenial=v=>ownerLimitDenial(v)&&costProjection(v)&&v.recovery.length>0;
+export const validateArtifact=v=>ownerArtifact(v)&&plainText(v.id)&&/^sha256:[0-9a-f]{64}$/.test(v.cas_ref)&&plainText(v.filename);
+export const validateSynthesis=v=>ownerSynthesis(v)&&text(v.answer)&&!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(v.answer);
+const member=(v)=>exact(v,["user_id","email","display_name","role"])&&[v.user_id,v.email,v.display_name].every(text)&&["OWNER","EDITOR","VIEWER"].includes(v.role);
+export const validateProject=(v)=>exact(v,["id","name","org_id","workspace_id","role","members","created_at","updated_at"])&&[v.id,v.name,v.org_id,v.workspace_id].every(text)&&["OWNER","EDITOR","VIEWER"].includes(v.role)&&Array.isArray(v.members)&&v.members.every(member)&&integer(v.created_at)&&integer(v.updated_at);
+export const validateRunAck=(v)=>exact(v,["run_id","state_hash","accepted_at","requested_route_id"])&&[v.run_id,v.state_hash,v.requested_route_id].every(text)&&integer(v.accepted_at);
+const dimension=(v)=>shape(v,["uncached_input","cache_read","cache_write","output"],["cache_write_class","cache_write_duration_s","provider_tier","long_context_band"])&&["uncached_input","cache_read","cache_write","output"].every(k=>integer(v[k])&&v[k]>=0)&&[v.cache_write_class,v.provider_tier,v.long_context_band].every(x=>x===undefined||x===null||text(x))&&(v.cache_write_duration_s===undefined||v.cache_write_duration_s===null||(integer(v.cache_write_duration_s)&&v.cache_write_duration_s>=0));
+const usage=(v)=>exact(v,["coverage","provider_id","model_id","observed_at","billable_dimensions"])&&["complete","incomplete"].includes(v.coverage)&&[v.provider_id,v.model_id].every(text)&&integer(v.observed_at)&&v.observed_at>=0&&Array.isArray(v.billable_dimensions)&&v.billable_dimensions.length>0&&v.billable_dimensions.every(dimension);
+export const validateAdmitted=(v)=>shape(v,["run_id","state_hash","result_hash","requested_route_id","profile","terminal","usage","events"],["duration_seconds"])&&[v.run_id,v.state_hash,v.result_hash,v.requested_route_id,v.profile].every(text)&&["ok","partial","blocked","refused","infeasible_physics","capability_gap"].includes(v.terminal)&&usage(v.usage)&&Array.isArray(v.events)&&(v.duration_seconds===undefined||v.duration_seconds===null||(integer(v.duration_seconds)&&v.duration_seconds>=0));
+export const validatePatCreated=(v)=>exact(v,["id","name","token","prefix","project_id","scopes","created_at","expires_at"])&&[v.id,v.name,v.token,v.prefix].every(text)&&(v.project_id===null||text(v.project_id))&&Array.isArray(v.scopes)&&v.scopes.every(s=>["project:read","project:execute"].includes(s))&&integer(v.created_at)&&integer(v.expires_at);
+export const validateDeviceAuthorization=(v)=>exact(v,["device_code","user_code","verification_uri","verification_uri_complete","expires_at","interval"])&&[v.device_code,v.user_code,v.verification_uri,v.verification_uri_complete].every(text)&&integer(v.expires_at)&&integer(v.interval)&&v.interval>=0;