@wenathlan/getry 2.0.166 → 2.0.168

package/README.md

@@ -20,7 +20,7 @@ pnpm dev
 # The family contract (wave 6-a)
 
 - `family.ts` — the single table of the eight siblings beside getry with the
-  spec §12 accent of each one; the shell rail foot and `tests/family.test.ts`
+  spec §12 accent of each one; the shell rail foot and `test/family.test.ts`
   both consume this one table.
 - `familyurl.ts` — the verbatim relative-url contract (`"../" + slug + "/"`,
   consolidated to the family variant) that keeps every cross-app link

package/cli.ts

@@ -727,7 +727,7 @@ async function cmdkeys(versionarg: string | undefined): Promise<void> {
         if (key) keys.push(key);
       }
       // write to a seed script the user can run
-      const seedpath = resolve(process.cwd(), "tests", "seedkeys.mjs");
+      const seedpath = resolve(process.cwd(), "test", "seedkeys.mjs");
       const seedcontent = [
         "/** seed keys — generated by gateway cli */",
         'import { PrismaClient } from "@prisma/client"',
@@ -748,9 +748,9 @@ async function cmdkeys(versionarg: string | undefined): Promise<void> {
         `console.log(\`registered \${keys.length} keys\`)`,
         "",
       ].join("\n");
-      mkdirSync(resolve(process.cwd(), "tests"), { recursive: true });
+      mkdirSync(resolve(process.cwd(), "test"), { recursive: true });
       writeFileSync(seedpath, seedcontent);
-      console.log(`\n${colors.green}created${colors.reset} tests/seedkeys.mjs — run: node tests/seedkeys.mjs`);
+      console.log(`\n${colors.green}created${colors.reset} test/seedkeys.mjs — run: node test/seedkeys.mjs`);
     }
   }
   console.log("");
@@ -791,9 +791,18 @@ async function cmdmodels(versionarg: string | undefined): Promise<void> {
 // ---------------------------------------------------------------------------
 
 async function cmdserve(portarg: string | undefined): Promise<void> {
-  const port = Number(portarg) || Number(process.env.PORT) || 3001;
-  process.env.PORT = String(port);
-  console.log(`${colors.cyan}starting gateway on port ${port}${colors.reset}`);
+  /* the gateway ports law (host/porta sorteados, never localhost literal):
+   * the caller pin rides when it carries a positive port (the arg lands in
+   * the env the transport main reads), the env pin rides when the env
+   * carries one, and when both stay silent the transport main draws the
+   * host and the port (binddraw.ts) — never a literal fallback */
+  const argport = Number(portarg);
+  if (portarg !== undefined && Number.isFinite(argport) && argport > 0) process.env.PORT = String(argport);
+  const pinned = Number(process.env.PORT);
+  const pinnedport = Number.isFinite(pinned) && pinned > 0 ? pinned : undefined;
+  console.log(
+    `${colors.cyan}starting gateway${pinnedport !== undefined ? ` on port ${pinnedport}` : " — the bind draws (host and port) since no env pin rides"}${colors.reset}`,
+  );
   /* the transport main loads lazily (the published-envelope law): the
    * console family — init through export, chat, help — runs on node
    * builtins alone inside the published envelope, and the serve seat

package/db.ts

@@ -20,6 +20,7 @@
 
 /// <reference types="better-sqlite3" />
 
+import { createOnboardingStore, type OnboardingLane, type OnboardingStore } from "@wenathlan/vault/onboardingstore";
 import { GATEWAYROUTES, GATEWAYVERSIONS, type GatewayRoute, type GatewayVersion } from "./gateway";
 import { LABEL_MANIFEST, LABEL_REVISION } from "./labels";
 
@@ -399,12 +400,6 @@ CREATE TABLE IF NOT EXISTS gateway_versions (
 );
 `;
 
-/** the prepared statements of the mirror, created once per process. */
-type OnboardingStatements = {
-  select: import("better-sqlite3").Statement;
-  upsert: import("better-sqlite3").Statement;
-};
-
 /** the prepared label statements of the mirror, created once per process. */
 type LabelStatements = {
   select: import("better-sqlite3").Statement;
@@ -421,7 +416,7 @@ type VersionStatements = {
 /** the cached driver bundle (null until the first node call). */
 let mirror: {
   db: import("better-sqlite3").Database;
-  statements: OnboardingStatements;
+  onboarding: OnboardingStore;
   labels: LabelStatements;
   versions: VersionStatements;
 } | null = null;
@@ -437,7 +432,7 @@ let mirror: {
  */
 async function openMirror(): Promise<{
   db: import("better-sqlite3").Database;
-  statements: OnboardingStatements;
+  onboarding: OnboardingStore;
   labels: LabelStatements;
   versions: VersionStatements;
 }> {
@@ -454,21 +449,31 @@ async function openMirror(): Promise<{
   db.exec(ONBOARDING_SCHEMA);
   db.exec(LABELS_SCHEMA);
   db.exec(GATEWAYVERSIONS_SCHEMA);
+  /* the onboarding store rides the vault factory over the mirror's own
+   * connection (the structural lane — execute, queryOne, exec — answered
+   * through one memoized prepare cache, so every statement stays prepared
+   * once per process): the seen-wins upsert —
+   * ON CONFLICT(visitor) DO UPDATE SET introseen = MAX(introseen, excluded.introseen),
+   * onboardingseen = MAX(onboardingseen, excluded.onboardingseen) — rides
+   * the shared mechanism, never a local copy of the sql, and the browser
+   * graph never gains a storage import — the factory module owns zero
+   * imports (the labelstore precedent). */
+  const prepared = new Map<string, import("better-sqlite3").Statement>();
+  const prepareCached = (sql: string): import("better-sqlite3").Statement => {
+    const cached = prepared.get(sql);
+    if (cached) return cached;
+    const statement = db.prepare(sql);
+    prepared.set(sql, statement);
+    return statement;
+  };
+  const onboardinglane: OnboardingLane = {
+    execute: (sql, params = []) => prepareCached(sql).run(...params),
+    queryOne: (sql, params = []) => prepareCached(sql).get(...params),
+    exec: (ddl) => db.exec(ddl),
+  };
   mirror = {
     db,
-    statements: {
-      select: db.prepare(
-        "SELECT id, visitor, introseen, onboardingseen, updatedAt FROM onboarding_states WHERE visitor = ?",
-      ),
-      upsert: db.prepare(
-        `INSERT INTO onboarding_states (visitor, introseen, onboardingseen, updatedAt)
-         VALUES (?, ?, ?, datetime('now'))
-         ON CONFLICT(visitor) DO UPDATE SET
-           introseen = MAX(introseen, excluded.introseen),
-           onboardingseen = MAX(onboardingseen, excluded.onboardingseen),
-           updatedAt = datetime('now')`,
-      ),
-    },
+    onboarding: createOnboardingStore(onboardinglane),
     labels: {
       select: db.prepare("SELECT id, text, revision, updatedAt, translated FROM labels WHERE id = ?"),
       selectAll: db.prepare("SELECT id, text, revision, updatedAt, translated FROM labels ORDER BY id ASC"),
@@ -514,15 +519,14 @@ export type OnboardingFlags = { introseen: boolean; onboardingseen: boolean };
  */
 export async function getonboardingstate(visitor: string): Promise<OnboardingFlags | undefined> {
   if (!isnode()) return undefined;
-  const { statements } = await openMirror();
-  const row = statements.select.get(visitor) as { introseen: number; onboardingseen: number } | undefined;
-  if (!row) return undefined;
-  return { introseen: row.introseen === 1, onboardingseen: row.onboardingseen === 1 };
+  const { onboarding } = await openMirror();
+  return onboarding.getOnboardingState(visitor);
 }
 
 /**
- * Marks one onboarding stage seen for a visitor — idempotent seen-wins
- * upsert (a stage seen anywhere stays seen), prepared and bound, never
+ * Marks one onboarding stage seen for a visitor — the idempotent seen-wins
+ * upsert of the vault store (a stage seen anywhere stays seen; the later
+ * stage implies the earlier — the flow order), prepared and bound, never
  * concatenated SQL.
  *
  * @param visitor the visitor key of the row.
@@ -531,8 +535,8 @@ export async function getonboardingstate(visitor: string): Promise<OnboardingFla
  */
 export async function setonboardingstage(visitor: string, stage: "intro" | "onboarding"): Promise<OnboardingFlags> {
   if (!isnode()) return { introseen: false, onboardingseen: false };
-  const { statements } = await openMirror();
-  statements.upsert.run(visitor, stage === "intro" ? 1 : 0, stage === "onboarding" ? 1 : 0);
+  const { onboarding } = await openMirror();
+  onboarding.setOnboardingStage(visitor, stage);
   return (await getonboardingstate(visitor)) ?? { introseen: false, onboardingseen: false };
 }
 

package/docs/features.md

@@ -16,8 +16,7 @@ every feature below is read from the code of the getry app root and the Sol them
 - cors handling — preflight and cors headers on every route.
 - response formats — chat completion, anthropic message and response shapes built from one pipeline.
 - gateway cli — `cli.ts` scaffolds and inspects gateway configs.
-- gateway probe — `gatewayprobe.ts` runs a manual chat round trip against a deployed host.
-- container smoke — `gatewaysmoke.ts` runs one full offline request cycle against the recorded openaicompat fixture.
+- gateway check — `gatewaycheck.ts` folds both check seats: the offline smoke (one full request cycle against the recorded openaicompat fixture) and the manual probe (a chat round trip against a deployed host).
 
 ## providers
 

package/docs/gateway.md

@@ -29,8 +29,7 @@
 - `oauth.ts` / `accounts.ts` / `recovery.ts` / `project.ts` — the provider oauth family, multi-account manager, recovery and project id discovery.
 - `db.ts` — the database contract: typed rows, in-memory seeds, HTTPS accessors, the health-aware round-robin key picker (`nextkeyrow`) and the better-sqlite3 mirror (onboarding states, labels and the `gateway_versions` route table).
 - `prismaconfig.ts` / `prismashim.ts` / `nodeshim.ts` — prisma schema path resolution and runtime shims.
-- `gatewayprobe.ts` — manual chat round trip against a deployed gateway (`GET /v1/models`, `POST /v1/chat/completions`).
-- `gatewaysmoke.ts` — offline container smoke: one full request cycle against the recorded openaicompat fixture.
+- `gatewaycheck.ts` — the two gateway check seats in one file: the offline container smoke (one full request cycle against the recorded openaicompat fixture) and the manual probe (chat round trip against a deployed gateway, `GET /v1/models`, `POST /v1/chat/completions`).
 - `registernvidiakeys.ts` — registers the 22 nvidia api keys into the `nvidiaKey` table.
 - `cli.ts` / `providercli.ts` — the gateway cli and the provider cli.
 - `versionregistry.ts`, `request.ts`, `search.ts`, `fingerprint.ts`, `constants.ts`, `antigravity.ts` — the antigravity/gemini-cli provider lineage: version resolution, request building, search, fingerprinting, endpoint constants.
@@ -122,4 +121,4 @@ the 7-level thinking ladder (`thinking.ts`), each level bound to a token budget:
 
 ## tests
 
-- 29 test files under `tests/` cover the gateway surface: gateway, gatewayversions (the 5/35 route table law, the sqlite mirror rows, the thinking chain), server (auth, engine, property, utils), llm, modelroute, promptlibrary, keyrotation (the health-aware key round-robin and the masking discipline), routerotation, thinkingladder (the registerable ladder and the tier/budget/chain/lane routing), streamfallback, intelligence, jsonpolicy, family, design, cli, providercli, onboardingstate, sandboxmodality, debonairlane, torture.llm, plus the provider lineage (constants, fingerprint, models, oauth) and the shared fixtures (`gatewayserver.ts`, `providerfixtures.ts`, `researchfixtures.ts`).
+- 29 test files under `test/` cover the gateway surface: gateway, gatewayversions (the 5/35 route table law, the sqlite mirror rows, the thinking chain), server (auth, engine, property, utils), llm, modelroute, promptlibrary, keyrotation (the health-aware key round-robin and the masking discipline), routerotation, thinkingladder (the registerable ladder and the tier/budget/chain/lane routing), streamfallback, intelligence, jsonpolicy, family, design, cli, providercli, onboardingstate, sandboxmodality, debonairlane, torture.llm, plus the provider lineage (constants, fingerprint, models, oauth) and the shared fixtures (`gatewayserver.ts`, `providerfixtures.ts`, `researchfixtures.ts`).

package/gatewaycheck.ts

@@ -0,0 +1,142 @@
+/**
+ * gatewaycheck — consolidated gateway check lane of the getry family
+ * @module gatewaycheck
+ * @family wave/gatewaycheck
+ * One keyed file per family: the former variant arms (gatewayprobe, gatewaysmoke)
+ * retired into this seat with every behavior preserved under the same name.
+ */
+
+import { startgatewayfixtureserver } from "./test/gatewayserver.ts";
+import type { baseurlconfig } from "./types.ts";
+
+/**
+ * the offline smoke seat of the 1.1.83 family: it starts the localhost fixture
+ * server, loads the built gateway module and runs one full request cycle
+ * against the recorded openaicompat fixture offline — no provider endpoint,
+ * no key, no external network — so the container image proves the gateway
+ * call path before it ships.
+ */
+export async function gatewaysmokeseat(): Promise<void> {
+  const server = await startgatewayfixtureserver();
+  try {
+    /* the smoke loads the BUILT gateway module — build/llm.js is a container
+     * build artifact a fresh checkout never carries, so the specifier rides a
+     * variable (tsc never fails on the absent artifact while the runtime
+     * keeps loading the built face) and the cast pins the module to the
+     * source contract that sits beside it. */
+    const builtpath = "./build/llm.js";
+    const gateway = (await import(builtpath)) as typeof import("./llm.ts");
+    const config: baseurlconfig = {
+      providerid: "smoke",
+      kind: "openaicompat",
+      baseurl: `http://127.0.0.1:${server.port}/openaicompat`,
+      enabled: true,
+      consented: true,
+      consentedat: Date.now(),
+      updatedat: Date.now(),
+    };
+    const outcome = await gateway.gatewaycall({
+      config,
+      model: "fixture-model-a",
+      messages: [{ role: "user", content: "draft one step" }],
+      requestid: "smoke-1",
+      transport: async (url: string, init: { method: string; headers: Record<string, string>; body?: string }) => {
+        const response = await fetch(url, { method: init.method, headers: init.headers, body: init.body });
+        return {
+          status: response.status,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: await response.text(),
+        };
+      },
+    });
+    if (!outcome.text.includes("goal")) throw new Error("The gateway smoke answer carries no goal field.");
+    if (outcome.usage?.totaltokens !== 55) throw new Error("The gateway smoke usage did not parse.");
+    const streamed = await gateway.gatewaystream({
+      config: { ...config, providerid: "smoke-stream" },
+      model: "fixture-model-a",
+      messages: [{ role: "user", content: "stream" }],
+      transport: async (url: string, init: { method: string; headers: Record<string, string>; body?: string }) => {
+        const response = await fetch(url, { method: init.method, headers: init.headers, body: init.body });
+        return {
+          status: response.status,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: await response.text(),
+        };
+      },
+    });
+    if (streamed.tokens.length !== 3)
+      throw new Error("The gateway smoke stream did not carry the three recorded deltas.");
+    console.log(
+      JSON.stringify({
+        valid: true,
+        requestid: outcome.requestid,
+        tokens: streamed.tokens.length,
+        usage: outcome.usage.totaltokens,
+      }),
+    );
+  } finally {
+    await server.close();
+  }
+}
+
+/**
+ * the live probe seat: a manual chat round trip against a deployed DevThink
+ * gateway (the ZAI sandbox deploy of the getry template). this seat is NOT
+ * wired into the deterministic gates: it needs the live network and the
+ * deployed host is a runtime setting, never a tracked constant of a gate.
+ * it exercises the exact surface the Sol chat client consumes: GET
+ * /v1/models (the picker) and POST /v1/chat/completions with the model
+ * "devthink" (content + reasoning_content on the answer turn).
+ */
+export async function gatewayprobeseat(base: string): Promise<void> {
+  /* GET /v1/models — the chat picker surface. */
+  const models = await fetch(`${base}/v1/models`);
+  if (!models.ok) {
+    console.error(`models probe failed: ${models.status}`);
+    process.exit(1);
+  }
+  const modellist = (await models.json()) as { data?: Array<{ id?: string }> };
+  const ids = (modellist.data ?? []).map((m) => m.id);
+  console.log(`models: ${ids.join(", ") || "(none)"}`);
+
+  /* POST /v1/chat/completions — one round trip on the chat surface. */
+  const chat = await fetch(`${base}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      model: "devthink",
+      messages: [{ role: "user", content: "Reply with exactly: gateway ok" }],
+      max_tokens: 20,
+    }),
+  });
+  if (!chat.ok) {
+    console.error(`chat probe failed: ${chat.status}`);
+    process.exit(1);
+  }
+  const answer = (await chat.json()) as {
+    choices?: Array<{ message?: { content?: string; reasoning_content?: string } }>;
+    usage?: unknown;
+  };
+  const turn = answer.choices?.[0]?.message;
+  console.log(`chat: ${JSON.stringify(turn?.content ?? "")}`);
+  console.log(`reasoning present: ${Boolean(turn?.reasoning_content)}`);
+  console.log(`usage: ${JSON.stringify(answer.usage ?? {})}`);
+
+  if (turn?.content !== "gateway ok") {
+    console.error("the gateway answered, but the round trip content drifted");
+    process.exit(1);
+  }
+  console.log("gateway probe: ok");
+}
+
+/* the dispatched entry the two seats ride: an http(s) URL argument answers
+ * the live probe seat (`node gatewaycheck.ts https://<deployed-gateway-host>`,
+ * the documented probe call), every other call answers the offline smoke
+ * seat (`node gatewaycheck.ts`, the container call). */
+const firstarg = (process.argv[2] ?? "").replace(/\/+$/, "");
+
+if (/^https?:\/\//.test(firstarg)) {
+  await gatewayprobeseat(firstarg);
+} else {
+  await gatewaysmokeseat();
+}