@homeflare/alchemy 0.23.0 → 0.25.0

package/src/litellm/pass-through-form.ts

@@ -0,0 +1,136 @@
+/**
+ * The wire body for a `LiteLLM.PassThroughEndpoint`, the comparison that decides whether it needs
+ * writing, and the refusals that stop a plan before it writes anything unsafe.
+ *
+ * ★ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER — the same reason netbox keeps `prefix-form.ts`
+ *   beside `prefix.ts` (S32/testing-and-docs.md).
+ *
+ * ⛔ PROPS ARE THE GENERATED TYPE, MINUS THE TWO FIELDS THIS RESOURCE OWNS ITSELF: `id` (a
+ *   deterministic physical name — pass-through-endpoint.ts) and `is_from_config` (response-only;
+ *   the vendor sets it, a declaration never does). Deriving `Props` with `Omit<>` rather than
+ *   hand-typing it means a vendor schema change that adds, removes or narrows a field is felt here
+ *   as a compiler error, not silently ignored.
+ */
+import { deepEqual } from 'alchemy/Diff';
+import type * as Generated from './generated/pass-through.ts';
+
+export type PassThroughEndpointProps = Omit<
+  Generated.PassThroughGenericEndpoint,
+  'id' | 'is_from_config'
+>;
+
+/** What `read` returns: the props plus the two vendor-owned fields, `id` now guaranteed present. */
+export type PassThroughEndpointAttributes = Omit<Generated.PassThroughGenericEndpoint, 'id'> & {
+  readonly id: string;
+};
+
+/** ⚠️ NetBox `settled()`'s pattern: only fields the SCHEMA gives a vendor default for, copied from it (not assumed). */
+export const settled = (props: PassThroughEndpointProps) => ({
+  auth: props.auth ?? true,
+  cost_per_request: props.cost_per_request ?? 0,
+  default_query_params: props.default_query_params ?? {},
+  headers: props.headers ?? {},
+  include_subpath: props.include_subpath ?? false,
+});
+
+/** The three fields whose absence the vendor's `exclude_none` update can never write (see client.ts). */
+export const NULLABLE_FIELDS = ['timeout', 'methods', 'guardrails'] as const;
+
+const isUnset = (value: unknown): boolean => value === undefined || value === null;
+
+/**
+ * ⚠️ BUILT AS A WIDER RECORD AND PRUNED, NOT AS THE GENERATED TYPE DIRECTLY.
+ *   `exactOptionalPropertyTypes` is on (packages/config/tsconfig.base.json), so writing
+ *   `timeout: undefined` into a `{ timeout?: number | null }` is a type error rather than an
+ *   absent key — the same reason `codegen/openapi.ts`'s `prune` exists, and the same fix.
+ */
+const prune = (value: Record<string, unknown>): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+
+/**
+ * Full body for CREATE. `id` is the deterministic physical name (pass-through-endpoint.ts), sent
+ * so a failed create is recoverable by `read` rather than orphaning a second row on retry.
+ */
+export const createBody = (
+  props: PassThroughEndpointProps,
+  id: string,
+): Generated.PassThroughGenericEndpoint =>
+  prune({
+    ...settled(props),
+    guardrails: isUnset(props.guardrails) ? undefined : props.guardrails,
+    id,
+    methods: isUnset(props.methods) ? undefined : props.methods,
+    path: props.path,
+    target: props.target,
+    timeout: isUnset(props.timeout) ? undefined : props.timeout,
+  }) as unknown as Generated.PassThroughGenericEndpoint;
+
+/**
+ * Partial body for UPDATE (`POST /{id}`). ⛔ ONLY FIELDS THIS DECLARATION ACTUALLY SETS — the
+ * vendor merges the parsed body with `model_dump(exclude_none=True)` (measured at v1.100.0), so an
+ * `undefined` OR an explicit `null` here would be dropped by the server anyway; sending neither is
+ * the same outcome with no request made when nothing changed (`Object.keys(body).length === 0`
+ * checked by the caller in pass-through-endpoint.ts).
+ */
+export const updateBody = (
+  props: PassThroughEndpointProps,
+): Partial<Generated.PassThroughGenericEndpoint> =>
+  prune({
+    ...settled(props),
+    guardrails: isUnset(props.guardrails) ? undefined : props.guardrails,
+    methods: isUnset(props.methods) ? undefined : props.methods,
+    path: props.path,
+    target: props.target,
+    timeout: isUnset(props.timeout) ? undefined : props.timeout,
+  }) as Partial<Generated.PassThroughGenericEndpoint>;
+
+/**
+ * Whether ANY of the three nullable fields went from set (in `live`) to unset (in `props`) — the
+ * one case `updateBody` cannot express, because the vendor's `exclude_none` merge silently keeps
+ * the old value instead of clearing it. Detected here so `pass-through-endpoint.ts` can plan a
+ * `replace` (delete-then-create) instead of an update that would look like it worked.
+ */
+export const needsReplace = (
+  live: PassThroughEndpointAttributes,
+  props: PassThroughEndpointProps,
+): boolean => NULLABLE_FIELDS.some((field) => !isUnset(live[field]) && isUnset(props[field]));
+
+/** Whether the live object already says what the declaration says — the `diff` "noop" test. */
+export const matches = (
+  live: PassThroughEndpointAttributes,
+  props: PassThroughEndpointProps,
+): boolean => {
+  const fixed = settled(props);
+  return (
+    live.target === props.target &&
+    live.auth === fixed.auth &&
+    live.cost_per_request === fixed.cost_per_request &&
+    live.include_subpath === fixed.include_subpath &&
+    deepEqual(live.headers, fixed.headers) &&
+    deepEqual(live.default_query_params, fixed.default_query_params) &&
+    (isUnset(props.timeout) ? isUnset(live.timeout) : live.timeout === props.timeout) &&
+    (isUnset(props.methods) ? isUnset(live.methods) : deepEqual(live.methods, props.methods)) &&
+    (isUnset(props.guardrails)
+      ? isUnset(live.guardrails)
+      : deepEqual(live.guardrails, props.guardrails))
+  );
+};
+
+/**
+ * A literal secret in a forwarded header (S25, house rule — not a vendor one; see
+ * pass-through-endpoint.ts). Case-insensitive on the header name; the reference form is LiteLLM's
+ * own, `os.environ/NAME` (`set_env_variables_in_header`, pass_through_endpoints.py:117-160 at the
+ * tag) — a missing variable on the proxy host leaves that literal string in the header, which
+ * nothing in the API can detect, so this is enforced here rather than trusted to the vendor.
+ */
+const SECRET_HEADER_NAMES = new Set(['authorization', 'x-api-key', 'cf-aig-authorization']);
+
+export const literalSecretHeaders = (
+  headers: Readonly<Record<string, unknown>> | undefined,
+): readonly string[] =>
+  Object.entries(headers ?? {})
+    .filter(
+      ([name, value]) =>
+        SECRET_HEADER_NAMES.has(name.toLowerCase()) && !String(value).includes('os.environ/'),
+    )
+    .map(([name]) => name);

package/src/litellm/providers.ts

@@ -0,0 +1,19 @@
+/**
+ * The LiteLLM provider, with its credential source, as one layer for a stack.
+ *
+ *     Layer.mergeAll(litellmProviders(), …the stack's other providers)
+ *
+ * ★ THE DEFAULT READS `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` AT CALL TIME (credentials.ts),
+ *   never at layer build — pass another `Layer.Layer<LitellmCredentials>` (see
+ *   `litellmCredentialsLayerFor` in a test) to source them another way.
+ * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime the same way it is
+ *   for `netboxProviders`-style families in this kit; a stack that already deploys anything over
+ *   HTTP already has one.
+ */
+import * as Layer from 'effect/Layer';
+import { type LitellmCredentials, litellmCredentialsLayer } from './credentials.ts';
+import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
+
+export const litellmProviders = (
+  creds: Layer.Layer<LitellmCredentials> = litellmCredentialsLayer,
+) => LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));

package/src/paperless/client.ts

@@ -0,0 +1,88 @@
+/**
+ * One authenticated call to the Paperless-ngx REST API at `/api`.
+ *
+ * ⚠️ `Authorization: Token <value>`, NOT `Bearer`. Paperless-ngx's `securitySchemes.tokenAuth`
+ *   (the v3.1.1 served schema) states the "Token" prefix explicitly — the same DRF
+ *   `TokenAuthentication` NetBox uses (netbox/client.ts), a different vendor, same convention.
+ *
+ * ⛔ `Accept: application/json; version=10` ON EVERY CALL. Paperless-ngx versions its API with
+ *   DRF's `AcceptHeaderVersioning` (`REST_FRAMEWORK.DEFAULT_VERSION = '10'`, measured against the
+ *   v3.1.1 source). Omitting the header still answers — DRF falls back to `DEFAULT_VERSION` — but
+ *   pinning it here means an estate upgrade that moves the default cannot silently change what
+ *   this package receives without a version bump of its own noticing.
+ *
+ * ⚠️ A LIST IS WRAPPED, A DETAIL IS NOT: `{count, next, previous, results: […]}` vs. the bare
+ *   object — the same DRF pagination shape NetBox uses.
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { PaperlessCredentials, type PaperlessCredentialsError } from './credentials.ts';
+import { type PaperlessError, PaperlessUnavailable, statusToError } from './errors.ts';
+
+const PATH_PREFIX = '/api';
+const API_VERSION = '10';
+
+export interface PaperlessList<T> {
+  readonly count: number;
+  readonly next: string | null;
+  readonly previous: string | null;
+  readonly results: readonly T[];
+}
+
+export type PaperlessRow = Record<string, unknown>;
+
+/**
+ * ⚠️ `PaperlessCredentials` IS PART OF THIS, NOT JUST `HttpClient`. `paperless()` reads the lazy
+ *   credentials service (`yield* yield* PaperlessCredentials`), so a stack that wires the
+ *   providers without also providing a credentials layer should fail to TYPECHECK, not fail at
+ *   the first call. `providers.ts` supplies `environmentLayer` by default for exactly this.
+ */
+export type PaperlessRequirements = HttpClient.HttpClient | PaperlessCredentials;
+
+/** One JSON call. Returns the parsed body, or `undefined` for an empty response (DELETE). */
+export const paperless = <T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+): Effect.Effect<T, PaperlessError | PaperlessCredentialsError, PaperlessRequirements> =>
+  Effect.gen(function* () {
+    const credentials = yield* yield* PaperlessCredentials;
+    const url = `${credentials.url}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({
+        Accept: `application/json; version=${API_VERSION}`,
+        Authorization: `Token ${credentials.token}`,
+      }),
+      // ⛔ Content-Type on `bodyText`, not the header map — `bodyText(s)` with no second argument
+      //   sets `text/plain` and overwrites a `Content-Type` set earlier via `setHeaders`, because
+      //   it is piped afterwards (measured against `@homeflare/alchemy/forgejo`, netbox/client.ts).
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(
+        Effect.mapError(
+          (cause) => new PaperlessUnavailable({ detail: String(cause), method, path, status: 0 }),
+        ),
+      );
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(statusToError(response.status, method, path, detail.slice(0, 500)));
+    }
+    const text = yield* response.text.pipe(
+      Effect.mapError(
+        () =>
+          new PaperlessUnavailable({
+            detail: 'body read failed',
+            method,
+            path,
+            status: response.status,
+          }),
+      ),
+    );
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });

package/src/paperless/constraint-guard.ts

@@ -0,0 +1,50 @@
+/**
+ * The generated tables, looked up by endpoint, and the refusal that stops a plan.
+ *
+ * ⛔ AN UNKNOWN KEY IS A DEFECT, NOT A REASON TO SKIP THE CHECK — the generator resolves every key
+ *   in its source scan against the vendor document, so a key absent here means the tables were
+ *   not regenerated, which the message says. Same posture as `../netbox/constraint-guard.ts`.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type EndpointConstraints,
+  type EndpointKey,
+  type PaperlessBody,
+  refusal,
+  violations,
+} from './constraints.ts';
+import { PAPERLESS_CONSTRAINTS } from './generated/constraints/index.ts';
+
+export { PAPERLESS_CONSTRAINTS };
+
+export const constraintsFor = (key: EndpointKey): EndpointConstraints => {
+  const table = PAPERLESS_CONSTRAINTS[key];
+  if (table === undefined) {
+    throw new Error(
+      `no vendor constraint table for '${key}'. It is named in this package but not generated: ` +
+        'run `bun codegen/paperless.ts` (see codegen/README.md).',
+    );
+  }
+  return table;
+};
+
+export const bodyViolations = (
+  key: EndpointKey,
+  body: PaperlessBody,
+  presence: boolean,
+): readonly string[] => violations(constraintsFor(key), body, { presence });
+
+/**
+ * ⛔ `Effect.die`, NOT `Effect.fail`. A declaration the vendor would reject is a DEFECT in the
+ *   stack file, not a recoverable condition.
+ */
+export const guardBody = (
+  key: EndpointKey | undefined,
+  body: PaperlessBody,
+  presence: boolean,
+): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    if (key === undefined) return Effect.void;
+    const found = bodyViolations(key, body, presence);
+    return found.length === 0 ? Effect.void : Effect.die(new Error(refusal(key, found)));
+  });

package/src/paperless/constraints.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The generated Paperless constraint tables, exercised at the boundary a plan actually checks:
+ * `bodyViolations` against the real generated data, not a literal table constructed by hand.
+ *
+ * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. Before `codegen/paperless.ts` and `generated/constraints/`
+ *   existed, `constraintsFor('paperless:POST /api/tags/')` threw "no vendor constraint table" —
+ *   there was nothing to import.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bodyViolations, constraintsFor } from './constraint-guard.ts';
+
+const CREATE = 'paperless:POST /api/tags/';
+
+describe('a 129-character name is refused, a 128-character one is not', () => {
+  test('129 plain characters', () => {
+    const found = bodyViolations(CREATE, { name: 'a'.repeat(129) }, true);
+    expect(found.some((f) => f.includes('name'))).toBe(true);
+  });
+
+  /** ⚠️ Counts CHARACTERS, not UTF-16 units — an astral emoji is one character to Django. */
+  test('128 astral characters (each a surrogate pair) passes the length check', () => {
+    const found = bodyViolations(CREATE, { name: '😀'.repeat(128) }, true);
+    expect(found.some((f) => f.includes('name'))).toBe(false);
+  });
+
+  test('129 astral characters is refused', () => {
+    const found = bodyViolations(CREATE, { name: '😀'.repeat(129) }, true);
+    expect(found.some((f) => f.includes('name'))).toBe(true);
+  });
+});
+
+describe('a 256-plus character match is refused', () => {
+  test('256 characters passes, 257 does not', () => {
+    expect(bodyViolations(CREATE, { match: 'a'.repeat(256), name: 'x' }, false)).toEqual([]);
+    const found = bodyViolations(CREATE, { match: 'a'.repeat(257), name: 'x' }, false);
+    expect(found.some((f) => f.includes('match'))).toBe(true);
+  });
+});
+
+describe('presence is create-only', () => {
+  test('a missing required name is refused on create', () => {
+    expect(bodyViolations(CREATE, {}, true).some((f) => f.includes('required'))).toBe(true);
+  });
+
+  /** ⚠️ An update is PATCH, deliberately partial — presence must not fire without `presence: true`. */
+  test('the same missing name is not refused on update', () => {
+    expect(bodyViolations(CREATE, {}, false)).toEqual([]);
+  });
+});
+
+describe('null is a value, not an absence', () => {
+  test('an explicit null owner on a table that carries no owner rule violates nothing', () => {
+    expect(bodyViolations(CREATE, { name: 'x', owner: null }, true)).toEqual([]);
+  });
+});
+
+describe('every generated table is reachable and carries its provenance', () => {
+  test('all four create endpoints resolve to a non-empty table', () => {
+    for (const key of [
+      'paperless:POST /api/tags/',
+      'paperless:POST /api/document_types/',
+      'paperless:POST /api/storage_paths/',
+      'paperless:POST /api/custom_fields/',
+    ]) {
+      expect(Object.keys(constraintsFor(key)).length).toBeGreaterThan(0);
+    }
+  });
+
+  test('an unknown key names the refresh command rather than silently enforcing nothing', () => {
+    expect(() => constraintsFor('paperless:POST /api/never/')).toThrow(
+      /bun codegen\/paperless\.ts/,
+    );
+  });
+});

package/src/paperless/constraints.ts

@@ -0,0 +1,111 @@
+/**
+ * Paperless-ngx's own rules, checked here, before the request is built.
+ *
+ * ★ THE SAME READER SHAPE AS `../netbox/constraints.ts`, AND FOR THE SAME REASON: both vendors
+ *   send a JSON body where a number stays a number and a boolean stays a boolean, so `String(v)`
+ *   at the door would be the exact mangling that incident (codegen/README.md) exists to prevent.
+ *   The table itself is generated by `bun codegen/paperless.ts` from the vendor's own OpenAPI
+ *   document — nothing here is hand-typed.
+ *
+ * ⚠️ WHAT THIS DELIBERATELY DOES NOT ENFORCE: a `format` name (a DRF validator run server-side); a
+ *   pattern the generator could not carry faithfully (codegen/py-pattern.ts), recorded verbatim as
+ *   `patternSource`; the `(name, owner)` uniqueness constraint (models.py) — that is `matching.ts`'s
+ *   job, not a per-field rule; and `CustomField.select_options`, which is not in the schema at all
+ *   (groundTruth: the serializer's own rule is unverified at 3.1.1 and this table cannot state a
+ *   rule the vendor document does not carry).
+ */
+
+export interface ParamConstraint {
+  readonly type?: string;
+  /** From the schema's `required` array. ⚠️ Checked on CREATE only. */
+  readonly required?: boolean;
+  readonly maxLength?: number;
+  readonly minLength?: number;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  /** ⚠️ `(string | number)[]` — `matching_algorithm`'s enum is numeric (`DataTypeEnum`'s is not). */
+  readonly enum?: readonly (string | number)[];
+  readonly pattern?: string;
+  readonly patternSource?: string;
+  readonly format?: string;
+  readonly default?: string;
+}
+
+export type EndpointConstraints = Readonly<Record<string, ParamConstraint>>;
+
+/** `paperless:POST /api/tags/` — exactly how the generated tables key an endpoint. */
+export type EndpointKey = string;
+
+export type PaperlessBody = Record<string, unknown>;
+
+export interface ViolationOptions {
+  /** ⛔ CREATE ONLY. A PATCH is deliberately partial, so presence there refuses every ordinary edit. */
+  readonly presence?: boolean;
+}
+
+/** ⚠️ `[...value].length`, NOT `value.length` — Django counts characters, JavaScript UTF-16 units. */
+const lengthOf = (value: string): number => [...value].length;
+
+const checkString = (name: string, value: string, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (rule.maxLength !== undefined && lengthOf(value) > rule.maxLength) {
+    out.push(`${name}: at most ${String(rule.maxLength)} characters`);
+  }
+  if (rule.minLength !== undefined && lengthOf(value) < rule.minLength) {
+    out.push(`${name}: at least ${String(rule.minLength)} characters`);
+  }
+  if (rule.enum !== undefined && !rule.enum.includes(value)) {
+    out.push(`${name}: must be one of ${rule.enum.join(', ')}`);
+  }
+  if (rule.pattern !== undefined && !new RegExp(rule.pattern).test(value)) {
+    out.push(`${name}: must match ${rule.patternSource ?? rule.pattern}`);
+  }
+  return out;
+};
+
+const checkNumber = (name: string, value: number, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (!Number.isFinite(value)) return out;
+  if (rule.minimum !== undefined && value < rule.minimum)
+    out.push(`${name}: at least ${String(rule.minimum)}`);
+  if (rule.maximum !== undefined && value > rule.maximum)
+    out.push(`${name}: at most ${String(rule.maximum)}`);
+  return out;
+};
+
+const checkValue = (name: string, value: unknown, rule: ParamConstraint): readonly string[] => {
+  if (typeof value === 'string') return checkString(name, value, rule);
+  if (typeof value === 'number') return checkNumber(name, value, rule);
+  return [];
+};
+
+/**
+ * Every vendor rule this body breaks. Pure — no network, no clock, no environment.
+ *
+ * ⚠️ `null` IS A VALUE, NOT AN ABSENCE — Paperless uses explicit `null` to clear a nullable
+ *   foreign key (`owner`, `parent`), so it must not trip the presence check, and no string/number
+ *   rule applies to it.
+ */
+export const violations = (
+  table: EndpointConstraints,
+  body: PaperlessBody,
+  options: ViolationOptions = {},
+): readonly string[] => {
+  const out: string[] = [];
+  for (const [name, rule] of Object.entries(table)) {
+    if (!Object.hasOwn(body, name)) {
+      if (options.presence === true && rule.required === true) out.push(`${name}: required`);
+      continue;
+    }
+    const value = body[name];
+    for (const item of Array.isArray(value) ? value : [value])
+      out.push(...checkValue(name, item, rule));
+  }
+  return out;
+};
+
+/** The message a plan dies with. */
+export const refusal = (endpoint: EndpointKey, found: readonly string[]): string =>
+  `${endpoint} would be rejected by the vendor:\n  - ${found.join('\n  - ')}\n` +
+  "These are Paperless-ngx's own limits, read from its served OpenAPI document " +
+  '(packages/alchemy/src/paperless/generated/constraints). Fix the declaration.';

package/src/paperless/credentials.ts

@@ -0,0 +1,69 @@
+/**
+ * Where the Paperless URL and token come from — S24's shape (alchemy-provider-standard): a lazy
+ * `Context.Service` whose VALUE is itself an `Effect`, resolved inside each operation with
+ * `yield* yield* PaperlessCredentials`. Resolving twice, not once at layer build, is what keeps a
+ * token out of any state the engine might persist and lets a consumer swap the source (an env var
+ * today, an OpenBao mint tomorrow) without touching a resource file.
+ *
+ * ⛔ NO DEFAULT HOST, AND NO DEFAULT TOKEN. A published package that fell back to a loopback
+ *   address would let a consumer who forgot the variable watch every call fail against a machine
+ *   that is not theirs, instead of being told which variable is missing.
+ * ⛔ THE TOKEN IS NEVER A PROP, NEVER AN ATTRIBUTE. Alchemy persists attributes unencrypted
+ *   (S25); nothing this family returns from `read`/`reconcile` may carry it.
+ */
+import * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+export class PaperlessCredentialsError extends Data.TaggedError('PaperlessCredentialsError')<{
+  readonly message: string;
+}> {}
+
+export interface PaperlessCredentialValue {
+  /** Trailing slash stripped, e.g. `https://paperless.example.com`. */
+  readonly url: string;
+  readonly token: string;
+}
+
+/**
+ * ★ `readEnvironment` NAMES EVERY VARIABLE IT CONSUMES (S24) — `PAPERLESS_URL`, `PAPERLESS_TOKEN`
+ *   — so a consumer's `alchemy provider check-env` (or an equivalent preflight) can list them.
+ */
+const readEnvironment: Effect.Effect<PaperlessCredentialValue, PaperlessCredentialsError> =
+  Effect.suspend(() => {
+    const url = process.env['PAPERLESS_URL'];
+    const token = process.env['PAPERLESS_TOKEN'];
+    if (url === undefined || url.trim() === '') {
+      return Effect.fail(
+        new PaperlessCredentialsError({
+          message: 'PAPERLESS_URL is not set. Point it at your Paperless-ngx instance.',
+        }),
+      );
+    }
+    if (token === undefined || token.trim() === '') {
+      return Effect.fail(
+        new PaperlessCredentialsError({
+          message:
+            'PAPERLESS_TOKEN is not set. Mint a scoped token and export it — never store it in Alchemy props.',
+        }),
+      );
+    }
+    return Effect.succeed({ token: token.trim(), url: url.trim().replace(/\/$/, '') });
+  });
+
+/**
+ * The lazy service. ⚠️ `Layer.succeed` registers the EFFECT, not its result — `readEnvironment`
+ *   runs once per `yield* yield*`, so a call after the variables are exported sees them even if
+ *   the layer itself was built before that (true in `fake-paperless.test.ts`, which sets the env
+ *   vars right before each call).
+ */
+export class PaperlessCredentials extends Context.Service<
+  PaperlessCredentials,
+  Effect.Effect<PaperlessCredentialValue, PaperlessCredentialsError>
+>()('PaperlessCredentials') {}
+
+export const environmentLayer: Layer.Layer<PaperlessCredentials> = Layer.succeed(
+  PaperlessCredentials,
+  readEnvironment,
+);

package/src/paperless/custom-field.test.ts

@@ -0,0 +1,74 @@
+/**
+ * `Paperless.CustomField.dataType` is create-only: a change is refused at plan time, never
+ * silently PATCHed and never routed to a replace. See custom-field.ts's header for why — a
+ * replace would delete the field's value on every document.
+ *
+ * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. `custom-field.ts` did not exist before this change.
+ */
+import { describe, expect, test } from 'bun:test';
+import { customFieldHandlers, dataTypeImmutable } from './custom-field.ts';
+import { run, withFake } from './fake-paperless.ts';
+
+describe('dataTypeImmutable, the pure rule', () => {
+  test('no refusal when the live value is unchanged', () => {
+    expect(
+      dataTypeImmutable({ data_type: 'string', id: 1 }, { dataType: 'string', name: 'x' }),
+    ).toBeUndefined();
+  });
+
+  test('a refusal when the live value differs, naming both values', () => {
+    const message = dataTypeImmutable(
+      { data_type: 'select', id: 1 },
+      { dataType: 'string', name: 'Status' },
+    );
+    expect(message).toMatch(/data_type is create-only/);
+    expect(message).toContain('live: select');
+    expect(message).toContain('declared: string');
+  });
+});
+
+describe('the live lifecycle refuses a data_type change', () => {
+  test('reconcile dies rather than PATCHing a changed data_type', async () => {
+    await withFake(async (fake) => {
+      await run(customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }));
+      const before = fake.seen.filter((s) => s.method !== 'GET').length;
+
+      await expect(
+        run(customFieldHandlers.reconcile({ news: { dataType: 'string', name: 'Status' } })),
+      ).rejects.toThrow(/data_type is create-only/);
+
+      // ⛔ NOTHING WAS WRITTEN — the refusal fires before the PATCH, not after a failed one.
+      expect(fake.seen.filter((s) => s.method !== 'GET').length).toBe(before);
+    });
+  });
+
+  test('a create followed by a declaration of the SAME data_type is a normal no-drift reconcile', async () => {
+    await withFake(async () => {
+      await run(customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }));
+      const after = await run(
+        customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }),
+      );
+      expect(after).toMatchObject({ dataType: 'select', name: 'Status' });
+    });
+  });
+
+  test('extraData still updates through a normal PATCH', async () => {
+    await withFake(async (fake) => {
+      await run(
+        customFieldHandlers.reconcile({
+          news: { dataType: 'select', extraData: { select_options: ['a'] }, name: 'Status' },
+        }),
+      );
+      await run(
+        customFieldHandlers.reconcile({
+          news: { dataType: 'select', extraData: { select_options: ['a', 'b'] }, name: 'Status' },
+        }),
+      );
+      const patch = fake.seen.find((s) => s.method === 'PATCH');
+      expect(patch).toBeDefined();
+      expect(JSON.parse(patch?.body ?? '{}')).toEqual({
+        extra_data: { select_options: ['a', 'b'] },
+      });
+    });
+  });
+});