@steve31415/baselib 3.15.0 → 3.17.0

package/README.md

@@ -1,9 +1,9 @@
 # baselib
 
-The Plasticine new-world shared platform library (`@steve31415/baselib`).
+The Plasticine fleet's shared platform library (`@steve31415/baselib`).
 What it provides and why: `docs/SPEC.md`. How it's put together:
 `docs/IMPL.md`. Full design rationale with alternatives:
-`~/migration/research/base-services-design.md` (step 5).
+`~/migration/research/base-services-design.md`.
 
 Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
 `app-update`, `llm`, `email`, and `twitter`. Browser exports: `log-browser`, `rum`,
@@ -34,17 +34,15 @@ deploy (`~/plasticine-way/docs/OPERATIONS.md`, "Deployment safety").
 first step of any production investigation (same doc, "Investigating
 production state").
 
-`twitter` provides Mirror2-first tweet lookup, TwitterAPI.io batch/search/
+`twitter` provides Mirror-first tweet lookup, TwitterAPI.io batch/search/
 article calls, and thread assembly through direct reply edges. It includes
 one level of quotes, article bodies and URL expansions. Use one shared
 `MirrorTweetClient(mirrorUrl, serviceFetch)` and `TwitterApiIoClient(key)`
 per run; `assembleThread(id, { api, mirror, ancestors: 'all' })` returns
 role-tagged tweets, source counts and warnings. Batch prefetching Mirror
-ids seeds the shared cache. Reader2 and Snip retain their copies for now.
+ids seeds the shared cache. Reader and Snip retain their copies for now.
 
 Releasing: bump `version`, commit, and run `npm run deploy` (Coder runs it
 automatically when integrating a baselib branch) — it pushes the `v<version>`
 tag, whose workflow gates on verify and publishes via OIDC, and waits for the
 registry (`~/plasticine-way/docs/OPERATIONS.md`, "Publishing baselib").
-
-Reflects Plasticine Way commit: see `docs/IMPL.md` footer.

package/dist/auth.d.ts

@@ -6,7 +6,7 @@ export declare const SESSION_COOKIE = "pw_session";
 /** The `code` in a 403 JSON body when a signed-in user is refused by the
  *  app's userAccess policy (as opposed to any other 403). */
 export declare const ACCESS_DENIED_CODE = "app_access_denied";
-/** A user's fleet role, assigned in auth2's users table. */
+/** A user's fleet role, assigned in auth's users table. */
 export type UserRole = 'owner' | 'invited';
 /** Which signed-in users an app admits. 'owner' (the default): only the
  *  fleet owner(s). 'invited': any active fleet user. */
@@ -39,7 +39,7 @@ export interface RequireIdentityOptions extends S2sOptions {
         missMs?: number;
     };
     /** Which signed-in users this app admits. Default 'owner': only users
-     *  whose auth2 role is owner. Pass 'invited' only for an app that is
+     *  whose auth role is owner. Pass 'invited' only for an app that is
      *  multi-user by design, and say so in its SPEC. Applies to browser
      *  sessions and the test bypass alike; service callers are governed by
      *  grants, not by this. */

package/dist/auth.js

@@ -12,7 +12,7 @@
 //      in-instance (10 min hits / 30 s misses — the old-world numbers).
 //
 // Then the user-access policy: by default an app admits only users whose
-// auth2 role is 'owner'; `userAccess: 'invited'` admits any active fleet
+// auth role is 'owner'; `userAccess: 'invited'` admits any active fleet
 // user. Being on the fleet sign-in allowlist never grants access by itself,
 // so a port that forgets the question is closed, not open. Service callers
 // are governed by grants, not by this policy.

package/dist/db.d.ts

@@ -111,7 +111,7 @@ export declare const FLEET_POOL_DEFAULTS: {
  *  rule: an advisory lock is not mutual exclusion. Our locks limit
  *  duplicated effort; code under one must be safe to overlap, and long
  *  work should probe the lock connection periodically (`select 1`) and
- *  stop on failure (Plasticine Way `docs/DATABASE.md`; mirror2's ingestion
+ *  stop on failure (Plasticine Way `docs/DATABASE.md`; mirror's ingestion
  *  loop is the reference).
  *
  *  `createPool` attaches all of this; exported for a pool an app built

package/dist/db.js

@@ -117,7 +117,7 @@ const instrumented = new WeakSet();
  *  rule: an advisory lock is not mutual exclusion. Our locks limit
  *  duplicated effort; code under one must be safe to overlap, and long
  *  work should probe the lock connection periodically (`select 1`) and
- *  stop on failure (Plasticine Way `docs/DATABASE.md`; mirror2's ingestion
+ *  stop on failure (Plasticine Way `docs/DATABASE.md`; mirror's ingestion
  *  loop is the reference).
  *
  *  `createPool` attaches all of this; exported for a pool an app built

package/dist/deploy/plan.d.ts

@@ -3,7 +3,7 @@ export declare const SHA40: RegExp;
 /** Lock staleness is judged from the GCS object's server-side timeCreated,
  *  never from anything the lock writer wrote (its clock may be wrong). */
 export declare function lockIsStale(timeCreatedIso: string, nowMs: number, staleMs: number): boolean;
-/** Consistent serving base across an app's services (notes2's rule,
+/** Consistent serving base across an app's services (notes's rule,
  *  generalized): all services on one SHA -> that SHA; some already on the
  *  target -> the rest must agree on one other SHA (the base); anything else
  *  is a skew that needs a human. A null buildSha (pre-unification revision)

package/dist/deploy/plan.js

@@ -11,7 +11,7 @@ export function lockIsStale(timeCreatedIso, nowMs, staleMs) {
         return false;
     return nowMs - created > staleMs;
 }
-/** Consistent serving base across an app's services (notes2's rule,
+/** Consistent serving base across an app's services (notes's rule,
  *  generalized): all services on one SHA -> that SHA; some already on the
  *  target -> the rest must agree on one other SHA (the base); anything else
  *  is a skew that needs a human. A null buildSha (pre-unification revision)

package/dist/deploy/types.d.ts

@@ -51,7 +51,7 @@ export interface DeployConfig {
      *  runtime-config change is a commit the deploy carries rather than a hand-run
      *  `gcloud run services update`. Undeclared vars are left as they are. */
     updateEnv?: Record<string, string>;
-    /** Refuse to deploy across a migrations/ diff (notes2 semantics). */
+    /** Refuse to deploy across a migrations/ diff (notes semantics). */
     refuseMigrationDiffOnDeploy?: boolean;
     /** Repo-relative path of an optional ES module exporting hooks. */
     hooks?: string;
@@ -114,10 +114,10 @@ export interface DeployHooks {
     publishAssets?: (ctx: HookContext) => Promise<void>;
     /** Runs after all gates pass, immediately before the first traffic switch. */
     preRelease?: (ctx: HookContext) => Promise<void>;
-    /** Runs right after traffic moves (e.g. todo2's announce-build). */
+    /** Runs right after traffic moves (e.g. todo's announce-build). */
     postTraffic?: (ctx: HookContext) => Promise<void>;
     /** Extra smoke checks after the shared health checks. */
     smoke?: (ctx: HookContext) => Promise<void>;
-    /** Runs after everything else succeeded (e.g. notes2's release state). */
+    /** Runs after everything else succeeded (e.g. notes's release state). */
     postSuccess?: (ctx: HookContext) => Promise<void>;
 }

package/dist/llm/complete.js

@@ -66,6 +66,7 @@ export async function llmComplete(request) {
                 temperature,
                 supportsTemperature: modelEntry.supportsTemperature ?? true,
                 supportsThinkingBudgetZero: modelEntry.supportsThinkingBudgetZero ?? true,
+                supportsForcedToolChoice: modelEntry.supportsForcedToolChoice ?? true,
                 effort: modelEntry.supportsEffort ? request.effort : undefined,
                 jsonSchema: request.jsonSchema,
                 apiKey,

package/dist/llm/models.d.ts

@@ -40,6 +40,15 @@ export interface ModelEntry {
      * when the caller's output budget leaves no meaningful headroom.
      */
     thinksByDefault?: boolean;
+    /**
+     * Whether this model accepts a forced `tool_choice` (`{type: 'tool'}`),
+     * which the Anthropic adapter uses to get `jsonSchema` output. Defaults to
+     * `true`. Opus 5.5 rejects it with a 400 ("tool_choice: type \"tool\" and
+     * \"any\" are not supported for this model.", verified 2026-09-22); for
+     * such models the adapter requests structured output via
+     * `output_config.format` instead.
+     */
+    supportsForcedToolChoice?: boolean;
 }
 /**
  * Output budget below which a `thinksByDefault` model is considered at risk of

package/dist/llm/models.js

@@ -10,7 +10,7 @@ export const THINKING_HEADROOM_WARN_TOKENS = 4096;
  */
 export const MODEL_REGISTRY = {
     // 2026-08 suite refresh: current models are claude-sonnet-5 / claude-opus-5
-    // (Anthropic), the gpt-5.6 sol/terra/luna family (OpenAI), and the Gemini
+    // (Anthropic; claude-opus-5-5 succeeded claude-opus-5 on 2026-09-22), the gpt-5.6 sol/terra/luna family (OpenAI), and the Gemini
     // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Older names stay
     // registered so existing callers keep working, but no fallback chain routes
     // through a retiring model: gemini-2.5-pro and gemini-2.5-flash shut down
@@ -106,6 +106,20 @@ export const MODEL_REGISTRY = {
         fallbacks: ['claude-sonnet-5', 'gemini-3.1-pro-preview'],
     },
     // --- Top tier ---
+    'claude-opus-5-5': {
+        provider: 'anthropic',
+        supportsEffort: true,
+        apiModelId: 'claude-opus-5-5',
+        fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
+        // All verified live 2026-09-22: rejects `temperature` and forced
+        // tool_choice (400 each); thinking is always on and its tokens count
+        // against `maxTokens`. With no `effort` passed the API runs at `medium`
+        // (Opus 5's default was `high`) — deliberately left as is (Steve,
+        // 2026-09-22: medium suits 5.5's capabilities).
+        supportsTemperature: false,
+        supportsForcedToolChoice: false,
+        thinksByDefault: true,
+    },
     'claude-opus-5': {
         provider: 'anthropic',
         supportsEffort: true,
@@ -136,14 +150,14 @@ export const MODEL_REGISTRY = {
     'gpt-5.6-sol': {
         provider: 'openai',
         apiModelId: 'gpt-5.6-sol',
-        fallbacks: ['claude-opus-5', 'gemini-3.1-pro-preview'],
+        fallbacks: ['claude-opus-5-5', 'gemini-3.1-pro-preview'],
         supportsTemperature: false,
         thinksByDefault: true,
     },
     'gpt-5.2': {
         provider: 'openai',
         apiModelId: 'gpt-5.2',
-        fallbacks: ['claude-opus-5', 'gemini-3.1-pro-preview'],
+        fallbacks: ['claude-opus-5-5', 'gemini-3.1-pro-preview'],
     },
     // Google's best Pro model as of 2026-08 — still Preview-labeled (no GA
     // Gemini 3.x Pro exists), but the only Pro-class option once 2.5-pro
@@ -151,7 +165,7 @@ export const MODEL_REGISTRY = {
     'gemini-3.1-pro-preview': {
         provider: 'gemini',
         apiModelId: 'gemini-3.1-pro-preview',
-        fallbacks: ['claude-opus-5', 'gpt-5.6-sol'],
+        fallbacks: ['claude-opus-5-5', 'gpt-5.6-sol'],
         // Thinks by default (thinking_level defaults to `high`).
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
@@ -161,6 +175,6 @@ export const MODEL_REGISTRY = {
     'gemini-2.5-pro': {
         provider: 'gemini',
         apiModelId: 'gemini-2.5-pro',
-        fallbacks: ['claude-opus-5', 'gpt-5.6-sol'],
+        fallbacks: ['claude-opus-5-5', 'gpt-5.6-sol'],
     },
 };

package/dist/llm/providers/anthropic.js

@@ -12,6 +12,51 @@ function classifyFinish(stopReason) {
         default: return 'other';
     }
 }
+/**
+ * Keywords `output_config.format` rejects outright with a 400 (verified on
+ * Opus 5.5, 2026-09-22). `minItems` is also rejected for values other than 0
+ * or 1, handled separately; `minLength`/`maxLength`, `pattern` and `format`
+ * are accepted.
+ */
+const UNSUPPORTED_FORMAT_KEYWORDS = [
+    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+    'maxItems', 'uniqueItems',
+];
+/**
+ * Transform a portable JSON schema into the dialect Anthropic's structured
+ * outputs (`output_config.format`) accepts: every object schema must set
+ * `additionalProperties: false`, and the numeric/array bounds listed above are
+ * dropped. The model then no longer enforces those bounds — callers validate
+ * the parsed result as they already must for truncation. Unlike forced
+ * tool_use, optional properties stay optional. Returns a deep copy — the
+ * caller's schema object is reused across failover attempts.
+ */
+function toOutputFormatSchema(node) {
+    if (Array.isArray(node))
+        return node.map(toOutputFormatSchema);
+    if (node === null || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (UNSUPPORTED_FORMAT_KEYWORDS.includes(key))
+            continue;
+        if (key === 'minItems' && typeof value === 'number' && value > 1)
+            continue;
+        // Maps whose values are schemas (not keywords): recurse per entry so a
+        // property that happens to be named `minimum` is kept.
+        if ((key === 'properties' || key === '$defs' || key === 'definitions')
+            && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            out[key] = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toOutputFormatSchema(v)]));
+            continue;
+        }
+        out[key] = toOutputFormatSchema(value);
+    }
+    const type = out.type;
+    if (type === 'object' || (Array.isArray(type) && type.includes('object'))) {
+        out.additionalProperties = false;
+    }
+    return out;
+}
 export const anthropicProvider = {
     name: 'anthropic',
     async complete(request) {
@@ -26,7 +71,7 @@ export const anthropicProvider = {
             max_tokens: request.maxTokens,
             messages: [{ role: 'user', content: request.prompt }],
         };
-        // Some models (Opus 4.7+, Sonnet 5, Fable 5) reject `temperature`
+        // Some models (Opus 4.7+, Sonnet 5, Fable 5, Opus 5.5) reject `temperature`
         // outright with a 400 — omit the field entirely rather than sending it.
         if (request.supportsTemperature) {
             body.temperature = request.temperature;
@@ -42,8 +87,16 @@ export const anthropicProvider = {
                 ? [{ type: 'text', text: request.systemPrompt, cache_control: { type: 'ephemeral' } }]
                 : request.systemPrompt;
         }
-        // JSON schema: use tool_use to get structured output
-        if (request.jsonSchema) {
+        // JSON schema: a forced tool_use call where the model allows it, else
+        // structured outputs (Opus 5.5 rejects forced tool_choice).
+        const useOutputFormat = request.jsonSchema !== undefined && !request.supportsForcedToolChoice;
+        if (request.jsonSchema && useOutputFormat) {
+            body.output_config = {
+                ...body.output_config,
+                format: { type: 'json_schema', schema: toOutputFormatSchema(request.jsonSchema.schema) },
+            };
+        }
+        else if (request.jsonSchema) {
             body.tools = [{
                     name: request.jsonSchema.name,
                     description: `Generate structured output matching the ${request.jsonSchema.name} schema`,
@@ -103,7 +156,18 @@ export const anthropicProvider = {
         const finishReason = data.stop_reason ?? undefined;
         let text;
         let json;
-        if (request.jsonSchema) {
+        if (useOutputFormat) {
+            text = data.content?.find((c) => c.type === 'text')?.text || '';
+            try {
+                json = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                // Truncated or malformed body: surface as json undefined, like the
+                // tool_use path, so the caller's truncation handling applies.
+                json = undefined;
+            }
+        }
+        else if (request.jsonSchema) {
             const toolUse = data.content?.find((c) => c.type === 'tool_use');
             json = toolUse?.input;
             text = json !== undefined ? JSON.stringify(json) : '';

package/dist/llm/types.d.ts

@@ -176,6 +176,13 @@ export interface ProviderCallRequest {
      * model would 400); non-zero budgets pass through unchanged.
      */
     supportsThinkingBudgetZero: boolean;
+    /**
+     * Whether the target model accepts a forced `tool_choice`, per the registry
+     * entry's `supportsForcedToolChoice` flag. When `false`, the Anthropic
+     * adapter gets `jsonSchema` output through `output_config.format` instead
+     * of a forced tool call. Other providers ignore it.
+     */
+    supportsForcedToolChoice: boolean;
     jsonSchema?: JsonSchema;
     apiKey: string;
     logger?: Logger;

package/dist/log-core.js

@@ -6,7 +6,7 @@
 // bounded, backed-off retries and per-batch identity
 // (~/migration/research/logging-reliability-design.md): every undelivered
 // batch either lands in Axiom or ends in an onGiveUp callback — the server
-// logger turns those into stdout drop markers that watchdog2's daily
+// logger turns those into stdout drop markers that watchdog's daily
 // ship-failure check counts. makeEvent also guards the shape of `meta`: every
 // distinct key is an Axiom column (see "Key-shape guard" below).
 export const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];

package/dist/log.d.ts

@@ -15,7 +15,7 @@ export interface LoggerOptions {
     context?: Record<string, unknown>;
     fetchFn?: typeof fetch;
 }
-/** Register a directly-constructed shipper (e.g. watchdog2's platform-dataset
+/** Register a directly-constructed shipper (e.g. watchdog's platform-dataset
  *  shipper) so flushAllLoggers and shutdown cover it too. */
 export declare function registerShipper(shipper: LogShipper): void;
 /** Flush every registered shipper. `final` is the shutdown path: time-boxed

package/dist/log.js

@@ -19,7 +19,7 @@ export { LogShipper, makeEvent, makeEvents, serializeError, setLogShapeStrict, t
 // with() children share their root's shipper, so registering loggers leaked
 // one entry per child.
 const allShippers = new Set();
-/** Register a directly-constructed shipper (e.g. watchdog2's platform-dataset
+/** Register a directly-constructed shipper (e.g. watchdog's platform-dataset
  *  shipper) so flushAllLoggers and shutdown cover it too. */
 export function registerShipper(shipper) {
     allShippers.add(shipper);

package/dist/rum.js

@@ -1,5 +1,5 @@
 // Real-user monitoring: Core Web Vitals shipped to the Axiom `rum` dataset
-// (targets: ~/migration/research/performance-targets.md). Configured by the
+// (targets: ~/plasticine-way/docs/PERFORMANCE.md). Configured by the
 // same pw-log-* meta tags as log-browser; token-less pages (local dev)
 // no-op. Metrics finalize on tab-hide, so the shipper flushes there with
 // keepalive fetch.

package/dist/s2s.js

@@ -99,7 +99,7 @@ export async function resolveS2sCaller(opts, headers, method, path) {
             // ("Wrong number of segments in token: <jwt>", "Invalid token signature:
             // <jwt>"), so the error is never logged as-is: the token's shape and a
             // redacted message only (PW LESSONS 2026-09-02 — log the shape, never
-            // the credential). Found by Mirror2's device-key design review.
+            // the credential). Found by Mirror's device-key design review.
             opts.logger?.warn('s2s token verification failed', {
                 path,
                 reason: redactToken(err instanceof Error ? err.message : String(err), m[1]),

package/dist/twitter-client.d.ts

@@ -55,7 +55,7 @@ export declare class TwitterApiError extends Error {
     constructor(message: string, apiCalls: number);
 }
 export declare function assertTweetId(id: string): void;
-/** Harvested from Reader2/Mirror2: bounded retries and timeout, four active
+/** Harvested from Reader/Mirror: bounded retries and timeout, four active
  * requests per shared client. Credentials and upstream bodies are never logged. */
 export declare class TwitterApiIoClient implements TwitterClient {
     private readonly apiKey;

package/dist/twitter-client.js

@@ -17,7 +17,7 @@ export function assertTweetId(id) {
     if (!/^\d{1,25}$/.test(id))
         throw new Error('Invalid tweet id');
 }
-/** Harvested from Reader2/Mirror2: bounded retries and timeout, four active
+/** Harvested from Reader/Mirror: bounded retries and timeout, four active
  * requests per shared client. Credentials and upstream bodies are never logged. */
 export class TwitterApiIoClient {
     apiKey;

package/dist/twitter-mirror.js

@@ -50,10 +50,10 @@ export class MirrorTweetClient {
             signal: AbortSignal.timeout(30_000),
         });
         if (!response.ok)
-            throw new Error(`Mirror2 tweets query HTTP ${response.status}`);
+            throw new Error(`Mirror tweets query HTTP ${response.status}`);
         const data = await response.json();
         if (!Array.isArray(data.records))
-            throw new Error('Mirror2 response has no records array');
+            throw new Error('Mirror response has no records array');
         const tweets = new Map();
         for (const r of data.records) {
             if (r.is_deleted || r.deleted_at)

package/dist/twitter.js

@@ -67,7 +67,7 @@ export async function assembleThread(id, options) {
                 add(await mirror.getTweetsByIds(missing), 'mirror2');
             }
             catch (error) {
-                warning('Mirror2 lookup failed', error);
+                warning('Mirror lookup failed', error);
             }
         const absent = missing.filter((key) => !records.has(key));
         if (absent.length)
@@ -85,10 +85,10 @@ export async function assembleThread(id, options) {
             add(conversation.tweets, 'mirror2');
             archivedAuthor = conversation.complete && conversation.tweets.some((tweet) => sameAuthor(tweet, linked));
             if (!conversation.complete)
-                warning('Mirror2 conversation reached its row limit; searching the author via API');
+                warning('Mirror conversation reached its row limit; searching the author via API');
         }
         catch (error) {
-            warning('Mirror2 conversation failed', error);
+            warning('Mirror conversation failed', error);
         }
     if (!archivedAuthor && /^\w+$/.test(linked.author.userName)) {
         let cursor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",