@xandreed/plugin-models 0.14.0 → 0.15.0

package/dist/ports/host-credentials.port.d.ts

@@ -1,6 +1,7 @@
 import { Context } from "effect";
 import type { Effect, Option } from "effect";
-import type { AuthError, ProviderId } from "@xandreed/core";
+import type { ProviderId } from "@xandreed/core";
+import type { AuthError } from "./auth-store.port.js";
 import type { CredentialInput } from "../auth/credential-input.entity.js";
 declare const HostCredentials_base: Context.ServiceClass<HostCredentials, "@xandreed/plugin-models/HostCredentials", {
     readonly load: Effect.Effect<ReadonlyMap<string, CredentialInput>, AuthError>;

package/dist/ports/model-call-completion.port.d.ts

@@ -0,0 +1,9 @@
+import { Context, Option } from "effect";
+import type { ModelSelection } from "@xandreed/core";
+/** Private execution-time purpose; utilities provide Helper without recording another call. */
+export declare const CurrentModelCallPurpose: Context.Reference<"Loop" | "Helper">;
+/** Private invocation metadata; a routed object call can use a provider's text implementation. */
+export declare const CurrentModelCallMethod: Context.Reference<"Text" | "Object" | "Stream">;
+export declare const CurrentModelCallSelection: Context.Reference<Option.Option<ModelSelection>>;
+/** Identifies which logical budget owns inherited invocation metadata. */
+export declare const CurrentModelCallMetadataOwner: Context.Reference<Option.Option<string & import("effect/Brand").Brand<"ModelCallId">>>;

package/dist/ports/model-call-completion.port.js

@@ -0,0 +1,2 @@
+import { Context, Option } from "effect";
+export const CurrentModelCallPurpose = Context.Reference("@xandreed/plugin-models/CurrentModelCallPurpose", { defaultValue: () => "Loop" }), CurrentModelCallMethod = Context.Reference("@xandreed/plugin-models/CurrentModelCallMethod", { defaultValue: () => "Text" }), CurrentModelCallSelection = Context.Reference("@xandreed/plugin-models/CurrentModelCallSelection", { defaultValue: () => Option.none() }), CurrentModelCallMetadataOwner = Context.Reference("@xandreed/plugin-models/CurrentModelCallMetadataOwner", { defaultValue: () => Option.none() });

package/dist/ports/model-endpoints.port.d.ts

@@ -1,46 +1,80 @@
 import { Context, Schema } from "effect";
+/** A base URL using chat completions, or an explicit Anthropic Messages protocol. @public */
+export declare const ModelEndpoint: Schema.Union<readonly [Schema.Struct<{
+    /** Absent keeps the existing chat-completions protocol. */
+    readonly api: Schema.optionalKey<Schema.Literal<"chat-completions">>;
+    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
+    readonly url: Schema.String;
+    readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
+    readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
+    readonly images: Schema.optionalKey<Schema.Boolean>;
+}>, Schema.Struct<{
+    readonly api: Schema.Literal<"anthropic-messages">;
+    /** The API key is opaque in either header; omission uses x-api-key. */
+    readonly auth: Schema.optionalKey<Schema.Literals<readonly ["x-api-key", "bearer"]>>;
+    /** False disables framework caching and refuses caller cache controls. */
+    readonly cacheControl: Schema.optionalKey<Schema.Boolean>;
+    /** Preserve the pinned SDK's version by default; an explicit version is sent verbatim. */
+    readonly apiVersion: Schema.optionalKey<Schema.String>;
+    /** Added to the SDK's own beta flags, in order with duplicates removed. */
+    readonly betas: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly url: Schema.String;
+    readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
+    readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
+    readonly images: Schema.optionalKey<Schema.Boolean>;
+}>]>;
+export type ModelEndpoint = typeof ModelEndpoint.Type;
 /**
- * An OpenAI-compatible endpoint a host names in configuration: the model
- * `<name>:<model id>` is sent to `<url>/chat/completions`. The key is
- * optional — a local server or a private gateway may need none. It comes
- * from `apiKey`, then the environment variable `apiKeyEnv` names, then the
- * AuthStore's key for `<name>`; with none, no Authorization header is sent.
- * An endpoint with its own key (`apiKey`, or a set `apiKeyEnv`) never reads
- * the AuthStore; an empty one (`apiKey: ""`, or a variable set to "") sends
- * no key. A host's code passes `apiKey` as a `Redacted` string so it
- * prints as `<redacted>` in errors and graph fingerprints; JSON
- * configuration names an environment variable in `apiKeyEnv` instead.
- * `standardOnly` (default true) sends only standard chat-completions fields.
- * `images` (default false) says its models read images: a user's images are
- * then sent as `image_url` parts, and a tool result's in one user message
- * after the tool results; without it they are label lines.
- * The endpoint's usage is read in full: cache reads and writes from
- * `prompt_tokens_details`, reasoning from `completion_tokens_details`.
+ * Endpoints by provider name; a name that matches a built-in provider replaces it.
+ *
+ * @public
  */
-export declare const ModelEndpoint: Schema.Struct<{
+export declare const ModelEndpoints: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+    /** Absent keeps the existing chat-completions protocol. */
+    readonly api: Schema.optionalKey<Schema.Literal<"chat-completions">>;
+    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
     readonly url: Schema.String;
     readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
-    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
     readonly images: Schema.optionalKey<Schema.Boolean>;
-}>;
-export type ModelEndpoint = typeof ModelEndpoint.Type;
-/** Endpoints by provider name; a name that matches a built-in provider replaces it. */
-export declare const ModelEndpoints: Schema.$Record<Schema.String, Schema.Struct<{
+}>, Schema.Struct<{
+    readonly api: Schema.Literal<"anthropic-messages">;
+    /** The API key is opaque in either header; omission uses x-api-key. */
+    readonly auth: Schema.optionalKey<Schema.Literals<readonly ["x-api-key", "bearer"]>>;
+    /** False disables framework caching and refuses caller cache controls. */
+    readonly cacheControl: Schema.optionalKey<Schema.Boolean>;
+    /** Preserve the pinned SDK's version by default; an explicit version is sent verbatim. */
+    readonly apiVersion: Schema.optionalKey<Schema.String>;
+    /** Added to the SDK's own beta flags, in order with duplicates removed. */
+    readonly betas: Schema.optionalKey<Schema.$Array<Schema.String>>;
     readonly url: Schema.String;
     readonly apiKey: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     readonly apiKeyEnv: Schema.optionalKey<Schema.String>;
-    readonly standardOnly: Schema.optionalKey<Schema.Boolean>;
     readonly images: Schema.optionalKey<Schema.Boolean>;
-}>>;
+}>]>>;
 export type ModelEndpoints = typeof ModelEndpoints.Type;
-/** The endpoints the models plugin was configured with; none by default. */
+/**
+ * The endpoints the models plugin was configured with; none by default.
+ *
+ * @public
+ */
 export declare const CurrentModelEndpoints: Context.Reference<{
     readonly [x: string]: {
         readonly url: string;
         readonly images?: boolean;
         readonly apiKey?: string | import("effect/Redacted").Redacted<string>;
-        readonly apiKeyEnv?: string;
+        readonly api?: "chat-completions";
         readonly standardOnly?: boolean;
+        readonly apiKeyEnv?: string;
+    } | {
+        readonly url: string;
+        readonly api: "anthropic-messages";
+        readonly images?: boolean;
+        readonly apiKey?: string | import("effect/Redacted").Redacted<string>;
+        readonly auth?: "x-api-key" | "bearer";
+        readonly apiKeyEnv?: string;
+        readonly cacheControl?: boolean;
+        readonly apiVersion?: string;
+        readonly betas?: readonly string[];
     };
 }>;

package/dist/ports/model-endpoints.port.js

@@ -1,13 +1,27 @@
 import { Context, Schema } from "effect";
-export const ModelEndpoint = Schema.Struct({
+const endpointFields = {
   url: Schema.String,
   apiKey: Schema.optionalKey(Schema.Union([
     Schema.String,
     Schema.Redacted(Schema.String).annotate({ message: "apiKey is a string or a Redacted string" })
   ]).annotate({ message: "apiKey is a string or a Redacted string" })),
   apiKeyEnv: Schema.optionalKey(Schema.String),
-  standardOnly: Schema.optionalKey(Schema.Boolean),
   images: Schema.optionalKey(Schema.Boolean)
-}).annotate({ messageUnexpectedKey: "not an option of a model endpoint" }), ModelEndpoints = Schema.Record(Schema.String, ModelEndpoint), CurrentModelEndpoints = Context.Reference("@xandreed/plugin-models/CurrentModelEndpoints", {
+};
+export const ModelEndpoint = Schema.Union([
+  Schema.Struct({
+    ...endpointFields,
+    api: Schema.optionalKey(Schema.Literal("chat-completions")),
+    standardOnly: Schema.optionalKey(Schema.Boolean)
+  }).annotate({ messageUnexpectedKey: "not an option of a chat-completions endpoint" }),
+  Schema.Struct({
+    ...endpointFields,
+    api: Schema.Literal("anthropic-messages"),
+    auth: Schema.optionalKey(Schema.Literals(["x-api-key", "bearer"])),
+    cacheControl: Schema.optionalKey(Schema.Boolean),
+    apiVersion: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/))),
+    betas: Schema.optionalKey(Schema.Array(Schema.String.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/))))
+  }).annotate({ messageUnexpectedKey: "not an option of an anthropic-messages endpoint" })
+]).annotate({ messageUnexpectedKey: "not an option of a model endpoint" }), ModelEndpoints = Schema.Record(Schema.String, ModelEndpoint), CurrentModelEndpoints = Context.Reference("@xandreed/plugin-models/CurrentModelEndpoints", {
   defaultValue: () => ({})
 });

package/dist/ports/model-retry-policy.port.d.ts

@@ -0,0 +1,17 @@
+import { Context, Option } from "effect";
+import type { ModelRequestCall } from "../transport/resilient-http-client.adapter.js";
+/** Read when a logical model call executes; the complete policy overrides the defaults. @public */
+export declare const CurrentModelRetryPolicy: Context.Reference<{
+    readonly maxAttempts: number;
+    readonly requestTimeoutMs: number;
+    readonly bodyIdleTimeoutMs: number;
+    readonly totalTimeoutMs: number;
+    readonly retryAfterMaxMs: number;
+    readonly backoff: {
+        readonly initialMs: number;
+        readonly maxMs: number;
+        readonly jitter: number;
+    };
+}>;
+/** Private per-call counter/deadline, shared only by its primary and fallback rung. */
+export declare const CurrentModelRequestCall: Context.Reference<Option.Option<ModelRequestCall>>;

package/dist/ports/model-retry-policy.port.js

@@ -0,0 +1,3 @@
+import { Context, Option } from "effect";
+import { modelRetryDefaults } from "../llm/model-retry-policy.entity.js";
+export const CurrentModelRetryPolicy = Context.Reference("@xandreed/plugin-models/CurrentModelRetryPolicy", { defaultValue: () => modelRetryDefaults }), CurrentModelRequestCall = Context.Reference("@xandreed/plugin-models/CurrentModelRequestCall", { defaultValue: () => Option.none() });

package/dist/ports/model-settings.port.d.ts

@@ -0,0 +1,32 @@
+import { Context } from "effect";
+/** Static per-model settings captured where the models layer is built. @public */
+export declare const CurrentModelSettings: Context.Reference<{
+    readonly [x: string]: {
+        readonly effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+        readonly limits?: {
+            readonly maxOutputTokens?: number;
+            readonly contextWindow?: number;
+        };
+        readonly thinking?: {
+            readonly _tag: "Off";
+        } | {
+            readonly _tag: "Adaptive";
+            readonly display?: "omitted" | "summarized";
+        } | {
+            readonly _tag: "Budget";
+            readonly budgetTokens: number;
+            readonly display?: "omitted" | "summarized";
+        } | {
+            readonly _tag: "BetweenTools";
+        };
+        readonly promptCache?: {
+            readonly _tag: "Auto";
+            readonly ttl: "5m" | "1h";
+        } | {
+            readonly _tag: "TopLevel";
+            readonly ttl: "5m" | "1h";
+        } | {
+            readonly _tag: "Off";
+        };
+    };
+}>;

package/dist/ports/model-settings.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export const CurrentModelSettings = Context.Reference("@xandreed/plugin-models/CurrentModelSettings", {
+  defaultValue: () => ({})
+});

package/dist/ports/models-transport.port.d.ts

@@ -1,5 +1,5 @@
-import { Context } from "effect";
-import type { Effect, Option, Redacted } from "effect";
+import { Context, Option } from "effect";
+import type { Effect, Redacted } from "effect";
 import type { Agent } from "node:http";
 import type { ProxyUnsupported } from "../transport/http-proxy.entity.js";
 /**
@@ -16,6 +16,8 @@ export type ModelsFetch = (input: string | URL, init?: RequestInit) => Promise<R
  * the runtime cannot use (`Proxy` outside Bun, `Agent` on Bun, whose `ws`
  * stand-in takes neither) fails the call rather than connecting past the
  * proxy.
+ *
+ * @public
  */
 export type WebSocketProxy = {
     readonly _tag: "Agent";
@@ -43,4 +45,9 @@ declare const ModelsTransport_base: Context.ServiceClass<ModelsTransport, "@xand
  */
 export declare class ModelsTransport extends ModelsTransport_base {
 }
+/** Internal provenance: only this exact managed direct instance yields to an explicit call-local fetch. */
+export declare const CurrentManagedModelsTransport: Context.Reference<Option.Option<{
+    readonly fetch: ModelsFetch;
+    readonly webSocketAgent?: (target: URL) => Effect.Effect<Option.Option<WebSocketProxy>, ProxyUnsupported>;
+}>>;
 export {};

package/dist/ports/models-transport.port.js

@@ -1,4 +1,7 @@
-import { Context } from "effect";
+import { Context, Option } from "effect";
 
 export class ModelsTransport extends Context.Service()("@xandreed/plugin-models/ModelsTransport") {
 }
+export const CurrentManagedModelsTransport = Context.Reference("@xandreed/plugin-models/CurrentManagedModelsTransport", {
+  defaultValue: Option.none
+});

package/dist/ports/prompt-cache-frame.port.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "effect";
+/** A captured SDK client reads this immutable frame in the invoking call's fiber. */
+export declare const CurrentPromptCacheFrame: Context.Reference<{
+    readonly candidates: readonly {
+        readonly control: {
+            readonly type: "ephemeral";
+            readonly ttl?: "5m" | "1h";
+        };
+        readonly priority: number;
+    }[];
+    readonly policy: {
+        readonly _tag: "Auto";
+        readonly ttl: "5m" | "1h";
+    } | {
+        readonly _tag: "TopLevel";
+        readonly ttl: "5m" | "1h";
+    } | {
+        readonly _tag: "Off";
+    };
+    readonly capability: boolean;
+}>;

package/dist/ports/prompt-cache-frame.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export const CurrentPromptCacheFrame = Context.Reference("@xandreed/plugin-models/CurrentPromptCacheFrame", {
+  defaultValue: () => ({ candidates: [], policy: { _tag: "Off" }, capability: !0 })
+});

package/dist/ports/settings-store.port.d.ts

@@ -0,0 +1,70 @@
+import { Context, Effect, Option, Schema } from "effect";
+declare const EngineSettings_base: Schema.Class<EngineSettings, Schema.Struct<{
+    readonly model: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly codeModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly fastModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly fallbackModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly maxAttempts: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<number, number, never, never>>>;
+    readonly budgetMillis: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<number, number, never, never>>>;
+    /** Selected after the model because the accepted levels are model-specific. */
+    readonly reasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+    readonly codeReasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+    readonly fastReasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+}>, {}>;
+/** @public */
+export declare class EngineSettings extends EngineSettings_base {
+}
+declare const SettingsError_base: Schema.Class<SettingsError, Schema.TaggedStruct<"SettingsError", {
+    readonly message: Schema.String;
+    /**
+     * `settings.corrupt`: the store's backing data could not be read or
+     * decoded. Nothing was read as defaults and nothing was written over it.
+     */
+    readonly code: Schema.optionalKey<Schema.Literal<"settings.corrupt">>;
+}>, import("effect/Cause").YieldableError>;
+/** @public */
+export declare class SettingsError extends SettingsError_base {
+}
+/**
+ * The three model roles a selection can be persisted under.
+ *
+ * @public
+ */
+export type ModelRole = "general" | "code" | "fast";
+/** The non-role keys the keyed setter may write — a closed vocabulary, so a
+ *  typo can never land a dead key in the user's config.
+ *
+ * @public
+ */
+export declare const SETTINGS_KEYS: readonly ["fallbackModel", "maxAttempts", "budgetMillis", "reasoningEffort", "codeReasoningEffort", "fastReasoningEffort"];
+/** @public */
+export type SettingsKey = (typeof SETTINGS_KEYS)[number];
+declare const SettingsStore_base: Context.ServiceClass<SettingsStore, "@xandreed/core/SettingsStore", {
+    readonly load: Effect.Effect<EngineSettings, SettingsError>;
+    /** Persist one role's model selection (a role choice); `None` clears
+     *  the role so it falls back to its default again. A selection that is
+     *  not `"<provider>:<modelId>"` fails with a `SettingsError` and writes
+     *  nothing. */
+    readonly setRole: (role: ModelRole, selection: Option.Option<string>) => Effect.Effect<void, SettingsError>;
+    /** Persist one non-role key from its STRING form (a settings edit): the
+     *  adapter validates + coerces per key ("true", "3", "provider:model")
+     *  and rejects a value that doesn't parse with a `SettingsError`,
+     *  writing nothing; `None` clears the key. */
+    readonly set: (key: SettingsKey, value: Option.Option<string>) => Effect.Effect<void, SettingsError>;
+}>;
+/**
+ * Read-through settings port. `load` re-reads the backing store on every call
+ * so a value changed mid-session takes effect on the next turn — callers must
+ * not cache the result across turns. A store may be read-only: then
+ * `setRole` and `set` fail with a `SettingsError` and write nothing. A store
+ * whose backing data cannot be read or decoded fails `load` and every write
+ * with a `SettingsError` of code `settings.corrupt` instead of reading it as
+ * defaults, so no write replaces settings it could not read.
+ * `settingsStoreConformance` (`@xandreed/plugin-models/conformance`) checks
+ * a store against this contract. Its key stays `@xandreed/core/SettingsStore`,
+ * the package it was first declared in: plugins' `provides` and hosts'
+ * bindings name it, so it never changes.
+ */
+export declare class SettingsStore extends SettingsStore_base {
+}
+export {};

package/dist/ports/settings-store.port.js

@@ -0,0 +1,33 @@
+import { Context, Effect, Option, Schema } from "effect";
+import { ReasoningEffort } from "@xandreed/core";
+const optionField = (schema) => Schema.OptionFromOptional(schema).pipe(Schema.withConstructorDefault(Effect.succeed(Option.none())));
+
+export class EngineSettings extends Schema.Class("EngineSettings")({
+  model: optionField(Schema.String),
+  codeModel: optionField(Schema.String),
+  fastModel: optionField(Schema.String),
+  fallbackModel: optionField(Schema.String),
+  maxAttempts: optionField(Schema.Number),
+  budgetMillis: optionField(Schema.Number),
+  reasoningEffort: optionField(ReasoningEffort),
+  codeReasoningEffort: optionField(ReasoningEffort),
+  fastReasoningEffort: optionField(ReasoningEffort)
+}) {
+}
+
+export class SettingsError extends Schema.TaggedError()("SettingsError", {
+  message: Schema.String,
+  code: Schema.optionalKey(Schema.Literal("settings.corrupt"))
+}) {
+}
+export const SETTINGS_KEYS = [
+  "fallbackModel",
+  "maxAttempts",
+  "budgetMillis",
+  "reasoningEffort",
+  "codeReasoningEffort",
+  "fastReasoningEffort"
+];
+
+export class SettingsStore extends Context.Service()("@xandreed/core/SettingsStore") {
+}

package/dist/ports/thinking-binding.port.d.ts

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+/**
+ * What the models plugin was configured to tell a model that binds thinking
+ * to the conversation (`thinkingPrefixMismatch`): `drop_block` for adaptive thinking by default;
+ * `provider-default` opts out of the explicit binding field.
+ */
+export declare const CurrentThinkingPrefixMismatch: Context.Reference<"error" | "provider-default" | "drop_block">;

package/dist/ports/thinking-binding.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+export const CurrentThinkingPrefixMismatch = Context.Reference("@xandreed/plugin-models/CurrentThinkingPrefixMismatch", {
+  defaultValue: () => "drop_block"
+});

package/dist/settings/localSettings.d.ts

@@ -1,3 +1,4 @@
 import { Layer } from "effect";
-import { SettingsStore } from "@xandreed/core";
+import { SettingsStore } from "../ports/settings-store.port.js";
+/** @public */
 export declare const LocalSettingsStoreLive: (cwd: string, home: string) => Layer.Layer<SettingsStore, never, never>;

package/dist/settings/localSettings.js

@@ -1,32 +1,29 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { Effect, Layer, Option } from "effect";
-import { asJsonRecord, parseJsonWarn, SettingsError, SettingsStore } from "@xandreed/core";
+import { SettingsError, SettingsStore } from "../ports/settings-store.port.js";
+import { readJsonObject, withFileLock, writeJsonObject } from "../storage/json-file.js";
 import { coerceSettingValue, ROLE_FIELDS, roleSelection, settingsFromRecord } from "./settings-value.entity.functions.js";
 const configPaths = (cwd, home) => [
   join(home, ".efferent", "config.json"),
   join(cwd, ".efferent", "config.json")
-], readConfig = (path) => Effect.tryPromise({ try: () => readFile(path, "utf-8"), catch: () => "missing" }).pipe(Effect.flatMap((text) => parseJsonWarn(text, path)), Effect.map(asJsonRecord), Effect.orElseSucceed(() => ({}))), writeKey = (cwd, key, value) => Effect.gen(function* () {
-  const path = join(cwd, ".efferent", "config.json"), current = yield* readConfig(path), next = Option.match(value, {
-    onNone: () => Object.fromEntries(Object.entries(current).filter(([k]) => k !== key)),
-    onSome: (v) => ({ ...current, [key]: v })
-  });
-  yield* writeConfigAtomic(path, next);
-});
+], readConfig = (path) => readJsonObject(path, (reason) => new SettingsError({
+  code: "settings.corrupt",
+  message: `${path} ${reason}: fix or remove it; nothing was read from it or written to it`
+})).pipe(Effect.map(Option.getOrElse(() => ({})))), writeKey = (cwd, key, value) => {
+  const path = join(cwd, ".efferent", "config.json");
+  return withFileLock(path)(Effect.gen(function* () {
+    const current = yield* readConfig(path), next = Option.match(value, {
+      onNone: () => Object.fromEntries(Object.entries(current).filter(([k]) => k !== key)),
+      onSome: (v) => ({ ...current, [key]: v })
+    });
+    yield* writeJsonObject(path, next, Option.none(), (reason) => new SettingsError({ message: `config.json write failed: ${reason}` }));
+  }));
+};
 export const LocalSettingsStoreLive = (cwd, home) => Layer.succeed(SettingsStore, {
-  load: Effect.forEach(configPaths(cwd, home), readConfig).pipe(Effect.map((configs) => settingsFromRecord(configs.reduce((acc, c) => ({ ...acc, ...c }), {})))),
+  load: Effect.forEach(configPaths(cwd, home), readConfig, { concurrency: 1 }).pipe(Effect.map((configs) => settingsFromRecord(configs.reduce((acc, c) => ({ ...acc, ...c }), {})))),
   setRole: (role, selection) => roleSelection(role, selection).pipe(Effect.flatMap((checked) => writeKey(cwd, ROLE_FIELDS[role], checked))),
   set: (key, value) => Option.match(value, {
     onNone: () => writeKey(cwd, key, Option.none()),
     onSome: (raw) => coerceSettingValue(key, raw).pipe(Effect.flatMap((coerced) => writeKey(cwd, key, Option.some(coerced))))
   })
 });
-const writeConfigAtomic = (path, config) => Effect.tryPromise({
-  try: async () => {
-    await mkdir(dirname(path), { recursive: !0 });
-    const tmp = `${path}.tmp-${process.pid}`;
-    await writeFile(tmp, JSON.stringify(config, null, 2), "utf-8");
-    await rename(tmp, path);
-  },
-  catch: (e) => new SettingsError({ message: `config.json write failed: ${String(e)}` })
-});

package/dist/settings/memory-settings.adapter.d.ts

@@ -1,10 +1,12 @@
 import { Layer } from "effect";
-import { EngineSettings, SettingsStore } from "@xandreed/core";
+import { EngineSettings, SettingsStore } from "../ports/settings-store.port.js";
 /**
  * `MemorySettingsStoreLive(initial)` — a SettingsStore that never touches
  * disk: one writable value for the layer's lifetime, starting at `initial`.
  * `setRole` and `set` check their value the way the file store does
  * (a `"<provider>:<modelId>"` selection; each key's string form) and refuse
  * one that does not parse, leaving the settings as they were.
+ *
+ * @public
  */
 export declare const MemorySettingsStoreLive: (initial?: EngineSettings) => Layer.Layer<SettingsStore>;

package/dist/settings/memory-settings.adapter.js

@@ -1,5 +1,5 @@
 import { Effect, Layer, SynchronizedRef } from "effect";
-import { EngineSettings, SettingsStore } from "@xandreed/core";
+import { EngineSettings, SettingsStore } from "../ports/settings-store.port.js";
 import { applyRole, applySetting } from "./settings-value.entity.functions.js";
 export const MemorySettingsStoreLive = (initial = new EngineSettings({})) => Layer.effect(SettingsStore, Effect.gen(function* () {
   const state = yield* SynchronizedRef.make(initial);

package/dist/settings/roleView.d.ts

@@ -1,5 +1,5 @@
 import { Layer } from "effect";
-import { SettingsStore } from "@xandreed/core";
+import { SettingsStore } from "../ports/settings-store.port.js";
 /**
  * A role-scoped VIEW of the settings store: `load` re-maps the general
  * `model` to the role's selection (falling back to `model` when the role is
@@ -7,5 +7,7 @@ import { SettingsStore } from "@xandreed/core";
  * LanguageModel router above all — runs on that role WITHOUT knowing roles
  * exist. Compose it under `LanguageModelLive` for the scope that should use
  * the role (e.g. the forge implementor on "code"); writes pass through.
+ *
+ * @public
  */
 export declare const roleModelView: (role: "code" | "fast") => Layer.Layer<SettingsStore, never, SettingsStore>;

package/dist/settings/roleView.js

@@ -1,5 +1,5 @@
 import { Effect, Layer, Option } from "effect";
-import { EngineSettings, SettingsStore } from "@xandreed/core";
+import { EngineSettings, SettingsStore } from "../ports/settings-store.port.js";
 export const roleModelView = (role) => Layer.effect(SettingsStore, Effect.map(SettingsStore, (inner) => ({
   load: Effect.map(inner.load, (s) => new EngineSettings({
     ...s,

package/dist/settings/settings-store.conformance.d.ts

@@ -0,0 +1,47 @@
+import { Effect } from "effect";
+import type { Context, Scope } from "effect";
+import type { ConformanceCheck } from "@xandreed/core/conformance";
+import type { SettingsStore } from "../ports/settings-store.port.js";
+type Store = Context.Service.Shape<typeof SettingsStore>;
+/**
+ * What the kit is told about a store, and can do to it beyond calling it.
+ *
+ * @public
+ */
+export interface SettingsStoreConformanceOptions {
+    /** Whether `setRole` and `set` write, or every write is refused. */
+    readonly writable: boolean;
+    /**
+     * Damage the store's backing data (a file that is not JSON) for the
+     * scope's lifetime, and repair it when the scope closes: the corrupt check.
+     * Damage what the store writes to, so a write that ignores the damage shows.
+     * A store with nothing to damage, such as one in memory, leaves it out.
+     */
+    readonly corrupt?: Effect.Effect<void, never, Scope.Scope>;
+}
+/**
+ * The SettingsStore contract. Every store: `load` is stable. A writable
+ * store: each role reads back what `setRole` wrote and clearing it returns
+ * the value before the set; `set` accepts each key's canonical string form
+ * and `load` gives it typed; `None` clears a key back to the value before the
+ * set; a value that does not parse (a selection that is not
+ * `"<provider>:<modelId>"`, a count that is not a whole number of at least
+ * 1, an unknown effort) fails with a `SettingsError` and changes
+ * nothing, through `set` and `setRole` alike. A read-only store refuses
+ * every write with a `SettingsError` and changes nothing.
+ *
+ * The kit writes the store's shared keys (settings have no per-check ids),
+ * and restores each key it touches; do not run it against settings that are
+ * in use. A key it would touch that holds a value the store must refuse (a
+ * selection that is not `"<provider>:<modelId>"`, a count below 1, left by
+ * an older, unchecked write) could not be put back, so the check that would
+ * touch it fails before writing anything.
+ *
+ * With `options.corrupt`, a store whose backing data cannot be read fails
+ * `load` (and, writable, `setRole` and `set`) with a `SettingsError` of code
+ * `settings.corrupt` instead of reading it as defaults.
+ *
+ * @public
+ */
+export declare const settingsStoreConformance: (store: Store, options: SettingsStoreConformanceOptions) => ReadonlyArray<ConformanceCheck>;
+export {};