@particle-academy/fancy-connector-core 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -1,103 +1,103 @@
-# Changelog
-
-All notable changes to `fancy-connector-core` are documented here, in
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
-
-**This package is pre-1.0, so breaking changes land in MINOR releases.** The
-version number is not a promise it can keep yet; the entries below are.
-
-## [Unreleased]
-
-## [0.1.0] — unreleased
-
-First cut. Extracted and generalised from the `_connector` shared runtime in the
-fancy-flow node marketplace, then rebuilt around the requirements in The Ripple
-Effect's packager brief, which came from five adapters dry-verified against real
-APIs.
-
-The connector **catalogue** lives in `fancy-connectors` and releases on its own
-clock; this package is the runtime it is written on.
-
-### Added
-
-- **Core runtime, TypeScript and PHP, with zero runtime dependencies in either
-  ecosystem.** WebCrypto and `fetch` on Node; `hash()` and cURL behind a
-  swappable `Transport` in PHP.
-- **`delivery` — a four-way failure classification.** `unreachable` /
-  `refused-explicitly` / `ambiguous` / `rejected`, with retryability a function
-  of the kind **and** the connector's declared idempotency. An unrecognised
-  error falls to `ambiguous`, never to safe.
-- **`DeliveryDeclaration`** — `idempotent` + a cited `why` + `minIntervalMs` +
-  `rateSource` (`documented` | `self-imposed`) + a dated `Citation`.
-- **`seam` — `ProviderAdapter` and `Connector`**, deliberately separate, plus
-  the written list of everything the package never owns: approval, liveness, the
-  approved-bytes comparison, consent, second review, journals, credential
-  storage.
-- **`text`** — `measure(text, unit)` over graphemes / characters / UTF-8 bytes,
-  and a `ByteRange` type producible only by a function that encoded the string.
-- **`render`** — pure, versioned (version **inside** the payload hash), loss
-  reported rather than applied, driven by a declarative `RenderRules` so most
-  providers need no rendering code at all.
-- **`chain`** — root fixed, parent advancing, with the post function as an
-  argument so threading is testable without a live session.
-- **`metrics`** — declared metric shapes, `compareShape()`,
-  `capabilityProblems()`, and `reported()` so *absent stays absent* is a
-  property of the code.
-- **`probe`** — dry-verify against the real API with a deliberately invalid
-  credential, per-provider `authStatuses`, a 2xx counted as a failure, and
-  offline reported as **skipped** rather than failed.
-- **`drift`** — API-drift *reporting*: a narrow projection of an OpenAPI
-  document against the operations a connector actually calls, a recorded-shape
-  fallback for the majority of providers that publish nothing, and `unchecked`
-  as a first-class outcome that is never collapsed into `clean`.
-- **Explicit-credentials resolution.** Credentials passed straight in bypass the
-  connection registry entirely; an incomplete set is a loud failure rather than
-  a silent fall-through.
-- **`CONNECTOR_API_VERSION` and `assertConnectorApi`** (`ConnectorApi` in PHP) —
-  the compatibility number that makes a separate release clock safe for a
-  catalogue whose connectors ship as VENDORED source. It moves only when the
-  surface a connector is written against moves, the window is the current
-  version and the one before, and a mismatch names which side is behind rather
-  than reporting "incompatible".
-
-#### Two things the PHP core does differently, and why
-
-- **A custom `Transport` must throw `TransportException`** — via
-  `unreachable()`, `ambiguous()` or `fromCurlErrno()` — to get the *always safe
-  to retry* case. PHP has no error-code vocabulary the way Node does, and
-  matching on message text is not an option: it is localised and changes between
-  HTTP-client versions. **What a consumer must do:** nothing if you use the
-  bundled `CurlTransport`. If you bind your own, throw `TransportException`
-  rather than a bare exception — a bare one is classified `Ambiguous`, which is
-  conservative and correct but gives up the retry a refused connection deserves.
-- **`RunIdentity` is bridged rather than implemented.** PHP interfaces are
-  nominal, so `FancyFlow\Runtime\RunIdentity` — which matches the shape exactly —
-  is not an instance of ours. `ForeignRunIdentity::adapt()` wraps any object
-  carrying the five members, and every `Idempotency` entry point runs its
-  argument through it. **What a consumer must do: nothing.** Pass `$ctx->run`
-  straight in, exactly as the TypeScript side does.
-
-### Fixed
-
-- **An ambiguous failure was retried on a non-idempotent connector.** The
-  runtime this was extracted from classified a thrown transport as
-  `ConnectorTransient` with `retryable = true` and retried it twice. A thrown
-  transport includes a timeout, which may be a request the provider already
-  acted on — so any connector without an idempotency key could be retried into a
-  silent double write. **What a consumer must do: nothing, unless you relied on
-  that behaviour.** A connector that genuinely is safe to repeat now says so
-  with `idempotent: true` and keeps its retries; everything else becomes
-  conservative, which is the correct direction.
-- **The sentence splitter broke URLs.** `splitToFit` treated every `.` as a
-  sentence terminator, so `https://example.test/x` was a candidate break point
-  and a link could land across two messages at a low limit. A terminator now
-  only ends a sentence when whitespace or the end follows it. **What a consumer
-  must do: nothing** — but any payload hash computed under the old splitting
-  will differ, so an approval recorded against it will correctly refuse.
-- **The core no longer imports a workflow engine.** The run identity used for
-  idempotency keys is declared structurally, so `fancy-flow`'s `RunIdentity`
-  satisfies it with no dependency in either direction and a host that has never
-  heard of a workflow engine can implement it.
-
-[Unreleased]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/Particle-Academy/fancy-connector-core/releases/tag/v0.1.0
+# Changelog
+
+All notable changes to `fancy-connector-core` are documented here, in
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+**This package is pre-1.0, so breaking changes land in MINOR releases.** The
+version number is not a promise it can keep yet; the entries below are.
+
+## [Unreleased]
+
+## [0.1.0] — unreleased
+
+First cut. Extracted and generalised from the `_connector` shared runtime in the
+fancy-flow node marketplace, then rebuilt around the requirements in The Ripple
+Effect's packager brief, which came from five adapters dry-verified against real
+APIs.
+
+The connector **catalogue** lives in `fancy-connectors` and releases on its own
+clock; this package is the runtime it is written on.
+
+### Added
+
+- **Core runtime, TypeScript and PHP, with zero runtime dependencies in either
+  ecosystem.** WebCrypto and `fetch` on Node; `hash()` and cURL behind a
+  swappable `Transport` in PHP.
+- **`delivery` — a four-way failure classification.** `unreachable` /
+  `refused-explicitly` / `ambiguous` / `rejected`, with retryability a function
+  of the kind **and** the connector's declared idempotency. An unrecognised
+  error falls to `ambiguous`, never to safe.
+- **`DeliveryDeclaration`** — `idempotent` + a cited `why` + `minIntervalMs` +
+  `rateSource` (`documented` | `self-imposed`) + a dated `Citation`.
+- **`seam` — `ProviderAdapter` and `Connector`**, deliberately separate, plus
+  the written list of everything the package never owns: approval, liveness, the
+  approved-bytes comparison, consent, second review, journals, credential
+  storage.
+- **`text`** — `measure(text, unit)` over graphemes / characters / UTF-8 bytes,
+  and a `ByteRange` type producible only by a function that encoded the string.
+- **`render`** — pure, versioned (version **inside** the payload hash), loss
+  reported rather than applied, driven by a declarative `RenderRules` so most
+  providers need no rendering code at all.
+- **`chain`** — root fixed, parent advancing, with the post function as an
+  argument so threading is testable without a live session.
+- **`metrics`** — declared metric shapes, `compareShape()`,
+  `capabilityProblems()`, and `reported()` so *absent stays absent* is a
+  property of the code.
+- **`probe`** — dry-verify against the real API with a deliberately invalid
+  credential, per-provider `authStatuses`, a 2xx counted as a failure, and
+  offline reported as **skipped** rather than failed.
+- **`drift`** — API-drift *reporting*: a narrow projection of an OpenAPI
+  document against the operations a connector actually calls, a recorded-shape
+  fallback for the majority of providers that publish nothing, and `unchecked`
+  as a first-class outcome that is never collapsed into `clean`.
+- **Explicit-credentials resolution.** Credentials passed straight in bypass the
+  connection registry entirely; an incomplete set is a loud failure rather than
+  a silent fall-through.
+- **`CONNECTOR_API_VERSION` and `assertConnectorApi`** (`ConnectorApi` in PHP) —
+  the compatibility number that makes a separate release clock safe for a
+  catalogue whose connectors ship as VENDORED source. It moves only when the
+  surface a connector is written against moves, the window is the current
+  version and the one before, and a mismatch names which side is behind rather
+  than reporting "incompatible".
+
+#### Two things the PHP core does differently, and why
+
+- **A custom `Transport` must throw `TransportException`** — via
+  `unreachable()`, `ambiguous()` or `fromCurlErrno()` — to get the *always safe
+  to retry* case. PHP has no error-code vocabulary the way Node does, and
+  matching on message text is not an option: it is localised and changes between
+  HTTP-client versions. **What a consumer must do:** nothing if you use the
+  bundled `CurlTransport`. If you bind your own, throw `TransportException`
+  rather than a bare exception — a bare one is classified `Ambiguous`, which is
+  conservative and correct but gives up the retry a refused connection deserves.
+- **`RunIdentity` is bridged rather than implemented.** PHP interfaces are
+  nominal, so `FancyFlow\Runtime\RunIdentity` — which matches the shape exactly —
+  is not an instance of ours. `ForeignRunIdentity::adapt()` wraps any object
+  carrying the five members, and every `Idempotency` entry point runs its
+  argument through it. **What a consumer must do: nothing.** Pass `$ctx->run`
+  straight in, exactly as the TypeScript side does.
+
+### Fixed
+
+- **An ambiguous failure was retried on a non-idempotent connector.** The
+  runtime this was extracted from classified a thrown transport as
+  `ConnectorTransient` with `retryable = true` and retried it twice. A thrown
+  transport includes a timeout, which may be a request the provider already
+  acted on — so any connector without an idempotency key could be retried into a
+  silent double write. **What a consumer must do: nothing, unless you relied on
+  that behaviour.** A connector that genuinely is safe to repeat now says so
+  with `idempotent: true` and keeps its retries; everything else becomes
+  conservative, which is the correct direction.
+- **The sentence splitter broke URLs.** `splitToFit` treated every `.` as a
+  sentence terminator, so `https://example.test/x` was a candidate break point
+  and a link could land across two messages at a low limit. A terminator now
+  only ends a sentence when whitespace or the end follows it. **What a consumer
+  must do: nothing** — but any payload hash computed under the old splitting
+  will differ, so an approval recorded against it will correctly refuse.
+- **The core no longer imports a workflow engine.** The run identity used for
+  idempotency keys is declared structurally, so `fancy-flow`'s `RunIdentity`
+  satisfies it with no dependency in either direction and a host that has never
+  heard of a workflow engine can implement it.
+
+[Unreleased]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Particle-Academy/fancy-connector-core/releases/tag/v0.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Particle Academy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,175 +1,175 @@
-# fancy-connector-core
-
-**The runtime under every Fancy connector.** Modes and estates, connections, one
-call path, a failure taxonomy that knows the difference between *it never
-arrived* and *nobody can tell*, deterministic fakers, webhook verification, pure
-versioned rendering, chain posting, declared metric shapes, credential-free
-probes, and API-drift reporting.
-
-Matched **TypeScript + PHP**, one repository, **zero runtime dependencies in
-either ecosystem**.
-
-```bash
-npm install @particle-academy/fancy-connector-core
-composer require particle-academy/fancy-connector-core
-```
-
----
-
-## It owns the wire. It never owns a gate.
-
-Approval, liveness, the approved-bytes comparison, consent, second review and
-every journal belong to the **host** — because each is enforced in one place and
-every connector inherits it from the host's dispatch path rather than
-implementing it.
-
-```ts
-await connector.call(target, { dryRun, credentials });
-//                              ^^^^^^  ^^^^^^^^^^^
-//                              yours   yours
-```
-
-Three of those promises are **tests**, not intentions:
-
-1. **Nothing here reads the environment.** No `process.env`, no `getenv`. Your
-   credential storage discipline — a gitignored file behind a whitelist, a secret
-   manager, Laravel config — stays yours, because the package cannot reach past
-   it.
-2. **Nothing here contacts a URL of its own.** No telemetry, no phone-home, no
-   default endpoint. Even the drift checker does not fetch: you fetch, and pass
-   the document in.
-3. **Nothing here retries an ambiguous failure** unless the connector declared
-   that repeating a request is harmless.
-
----
-
-## The one that matters: retry, without ever sending twice
-
-A network hiccup should not lose a call. A retry after a request that succeeded
-and whose response was lost is a **double write** — the exact failure an
-idempotency gate exists to prevent, arriving through the door marked
-*reliability*.
-
-Nearly every retry helper reconciles those the same way and loses: it catches an
-error, waits, and tries again, because from the caller's side all failures look
-alike.
-
-| what happened | did the provider receive it? | retry? |
-|---|---|---|
-| DNS failure, connection refused | **no** | always safe |
-| HTTP 429 / 5xx | **yes**, and it explicitly refused | safe — it says it did nothing |
-| timeout, abort, **anything unrecognised** | **unknown** | only where the connector is idempotent |
-| other 4xx | yes, and the answer was a real no | never |
-
-```ts
-import { classifyError, shouldRetry } from "@particle-academy/fancy-connector-core";
-
-shouldRetry(classifyError(err).kind, { idempotent: connector.delivery.idempotent });
-```
-
-`idempotent` defaults to **false**, and `delivery.why` must cite the mechanism —
-`Idempotency-Key`, or the absence of one — because `idempotent: true` is the one
-claim whose failure is a public duplicate.
-
----
-
-## Text, and two one-line bugs that ASCII hides
-
-```ts
-import { measure, linkRanges, sliceByteRange } from "@particle-academy/fancy-connector-core";
-
-measure("👍", "graphemes");   // 1   — "👍".length is 2
-linkRanges("👍 https://example.test");  // UTF-8 BYTE ranges, not char offsets
-```
-
-`ByteRange` is a **type**, producible only by a function that encoded the string.
-A character-offset implementation is correct for ASCII and silently corrupts the
-*link* on any post containing an emoji — the post looks fine and goes somewhere
-wrong.
-
----
-
-## Rendering: pure, versioned, honest about loss
-
-```ts
-const payload = render(copy, {
-  limit: 300, unit: "graphemes", thread: true, links: true, label: "Bluesky",
-});
-
-payload.segments;  // one entry per message; more than one means a thread
-payload.problems;  // what could NOT be fitted. Never silently applied.
-await payloadHash(payload);  // RENDERER_VERSION is INSIDE the hash
-```
-
-Show the payload before you approve it, recompute it at dispatch, refuse on
-mismatch. That is the only way "what was approved is what was sent" survives the
-existence of adaptation — and the renderer version being inside the hash is what
-stops it being checked separately and forgotten.
-
----
-
-## Threading
-
-```ts
-await postChain(payload.segments.map((s) => s.text), answering, post);
-```
-
-Root fixed at the top of the chain; parent advancing to whatever was just posted.
-Reverse them and every message attaches to the first — a fan, not a thread — and
-the provider's response looks identical either way. The post function is an
-**argument** so that is reachable by a test.
-
----
-
-## Probes: an auth error proves the transport
-
-A connector written from documentation can be wrong in three ways that look
-identical until a credential arrives: the URL is wrong, the request shape is
-wrong, or the error handling never runs. **All three are invisible to a fake
-server, because a fake server agrees with whatever your code does.**
-
-So call the real API with a deliberately invalid credential and require an
-auth-shaped refusal.
-
-- `authStatuses` is declared per provider — a Discord webhook answers `404` for
-  an unknown id, so 404 IS its auth answer.
-- **A 2xx is a failure.** The credential is reaching nothing.
-- **Offline is `skip`, never `fail`.** A check that goes red on a train gets
-  ignored, and is then worth nothing when it goes red for real.
-
----
-
-## Drift: it reports, it never adapts
-
-A connector's worst failure is silent — the provider changes its API and nothing
-says so until something breaks.
-
-**And the fix is not a connector that reshapes itself.** That connector cannot be
-reviewed, its behaviour depends on when it ran, and adaptation is only ever a
-guess at intent. So:
-
-> Drift reports. The provider decides. A person acts.
-
-Drift also never changes runtime behaviour: it runs out of band, and a check that
-failed a working call because a *document* changed would be a self-inflicted
-outage.
-
-What is checked is a narrow projection, not a diff — *for the operations this
-connector actually calls, do the path, method, sent fields and read fields still
-exist?* Where a provider publishes no spec (most do not), the fallback is a
-recorded shape: field **names** only.
-
-`outcome` is `clean` | `drifted` | **`unchecked`**. The third is never collapsed
-into the first — a checker that could not see is not a checker that saw nothing
-wrong.
-
----
-
-## Documentation
-
-- [`AGENTS.md`](./AGENTS.md) — the invariants, the traps, and what a change here
-  breaks.
-- `.ai/plans/fancy-connectors.md` in the envelope — the architecture, the
-  Socialite seam, the drift research, and every decision with its reason.
-
-MIT.
+# fancy-connector-core
+
+**The runtime under every Fancy connector.** Modes and estates, connections, one
+call path, a failure taxonomy that knows the difference between *it never
+arrived* and *nobody can tell*, deterministic fakers, webhook verification, pure
+versioned rendering, chain posting, declared metric shapes, credential-free
+probes, and API-drift reporting.
+
+Matched **TypeScript + PHP**, one repository, **zero runtime dependencies in
+either ecosystem**.
+
+```bash
+npm install @particle-academy/fancy-connector-core
+composer require particle-academy/fancy-connector-core
+```
+
+---
+
+## It owns the wire. It never owns a gate.
+
+Approval, liveness, the approved-bytes comparison, consent, second review and
+every journal belong to the **host** — because each is enforced in one place and
+every connector inherits it from the host's dispatch path rather than
+implementing it.
+
+```ts
+await connector.call(target, { dryRun, credentials });
+//                              ^^^^^^  ^^^^^^^^^^^
+//                              yours   yours
+```
+
+Three of those promises are **tests**, not intentions:
+
+1. **Nothing here reads the environment.** No `process.env`, no `getenv`. Your
+   credential storage discipline — a gitignored file behind a whitelist, a secret
+   manager, Laravel config — stays yours, because the package cannot reach past
+   it.
+2. **Nothing here contacts a URL of its own.** No telemetry, no phone-home, no
+   default endpoint. Even the drift checker does not fetch: you fetch, and pass
+   the document in.
+3. **Nothing here retries an ambiguous failure** unless the connector declared
+   that repeating a request is harmless.
+
+---
+
+## The one that matters: retry, without ever sending twice
+
+A network hiccup should not lose a call. A retry after a request that succeeded
+and whose response was lost is a **double write** — the exact failure an
+idempotency gate exists to prevent, arriving through the door marked
+*reliability*.
+
+Nearly every retry helper reconciles those the same way and loses: it catches an
+error, waits, and tries again, because from the caller's side all failures look
+alike.
+
+| what happened | did the provider receive it? | retry? |
+|---|---|---|
+| DNS failure, connection refused | **no** | always safe |
+| HTTP 429 / 5xx | **yes**, and it explicitly refused | safe — it says it did nothing |
+| timeout, abort, **anything unrecognised** | **unknown** | only where the connector is idempotent |
+| other 4xx | yes, and the answer was a real no | never |
+
+```ts
+import { classifyError, shouldRetry } from "@particle-academy/fancy-connector-core";
+
+shouldRetry(classifyError(err).kind, { idempotent: connector.delivery.idempotent });
+```
+
+`idempotent` defaults to **false**, and `delivery.why` must cite the mechanism —
+`Idempotency-Key`, or the absence of one — because `idempotent: true` is the one
+claim whose failure is a public duplicate.
+
+---
+
+## Text, and two one-line bugs that ASCII hides
+
+```ts
+import { measure, linkRanges, sliceByteRange } from "@particle-academy/fancy-connector-core";
+
+measure("👍", "graphemes");   // 1   — "👍".length is 2
+linkRanges("👍 https://example.test");  // UTF-8 BYTE ranges, not char offsets
+```
+
+`ByteRange` is a **type**, producible only by a function that encoded the string.
+A character-offset implementation is correct for ASCII and silently corrupts the
+*link* on any post containing an emoji — the post looks fine and goes somewhere
+wrong.
+
+---
+
+## Rendering: pure, versioned, honest about loss
+
+```ts
+const payload = render(copy, {
+  limit: 300, unit: "graphemes", thread: true, links: true, label: "Bluesky",
+});
+
+payload.segments;  // one entry per message; more than one means a thread
+payload.problems;  // what could NOT be fitted. Never silently applied.
+await payloadHash(payload);  // RENDERER_VERSION is INSIDE the hash
+```
+
+Show the payload before you approve it, recompute it at dispatch, refuse on
+mismatch. That is the only way "what was approved is what was sent" survives the
+existence of adaptation — and the renderer version being inside the hash is what
+stops it being checked separately and forgotten.
+
+---
+
+## Threading
+
+```ts
+await postChain(payload.segments.map((s) => s.text), answering, post);
+```
+
+Root fixed at the top of the chain; parent advancing to whatever was just posted.
+Reverse them and every message attaches to the first — a fan, not a thread — and
+the provider's response looks identical either way. The post function is an
+**argument** so that is reachable by a test.
+
+---
+
+## Probes: an auth error proves the transport
+
+A connector written from documentation can be wrong in three ways that look
+identical until a credential arrives: the URL is wrong, the request shape is
+wrong, or the error handling never runs. **All three are invisible to a fake
+server, because a fake server agrees with whatever your code does.**
+
+So call the real API with a deliberately invalid credential and require an
+auth-shaped refusal.
+
+- `authStatuses` is declared per provider — a Discord webhook answers `404` for
+  an unknown id, so 404 IS its auth answer.
+- **A 2xx is a failure.** The credential is reaching nothing.
+- **Offline is `skip`, never `fail`.** A check that goes red on a train gets
+  ignored, and is then worth nothing when it goes red for real.
+
+---
+
+## Drift: it reports, it never adapts
+
+A connector's worst failure is silent — the provider changes its API and nothing
+says so until something breaks.
+
+**And the fix is not a connector that reshapes itself.** That connector cannot be
+reviewed, its behaviour depends on when it ran, and adaptation is only ever a
+guess at intent. So:
+
+> Drift reports. The provider decides. A person acts.
+
+Drift also never changes runtime behaviour: it runs out of band, and a check that
+failed a working call because a *document* changed would be a self-inflicted
+outage.
+
+What is checked is a narrow projection, not a diff — *for the operations this
+connector actually calls, do the path, method, sent fields and read fields still
+exist?* Where a provider publishes no spec (most do not), the fallback is a
+recorded shape: field **names** only.
+
+`outcome` is `clean` | `drifted` | **`unchecked`**. The third is never collapsed
+into the first — a checker that could not see is not a checker that saw nothing
+wrong.
+
+---
+
+## Documentation
+
+- [`AGENTS.md`](./AGENTS.md) — the invariants, the traps, and what a change here
+  breaks.
+- `.ai/plans/fancy-connectors.md` in the envelope — the architecture, the
+  Socialite seam, the drift research, and every decision with its reason.
+
+MIT.