@getbourdon/participants 0.1.0

package/LICENSE

@@ -0,0 +1,92 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             RADLAB LLC
+Licensed Work:        Bourdon Version 0.2.0 or later. The Licensed Work is (c) 2026
+                      RADLAB LLC.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      Your use does not include offering the Licensed Work to third
+                      parties on a hosted or embedded basis in order to compete with
+                      RADLAB LLC's paid version(s) of the Licensed Work. For purposes
+                      of this license:
+
+                      A "competitive offering" is a Product that is offered to third
+                      parties on a paid basis, including through paid support
+                      arrangements, that significantly overlaps with the capabilities
+                      of RADLAB LLC's paid version(s) of the Licensed Work. If Your
+                      Product is not a competitive offering when You first make it
+                      generally available, it will not become a competitive offering
+                      later due to RADLAB LLC releasing a new version of the Licensed
+                      Work with additional capabilities. In addition, Products that
+                      are not provided on a paid basis are not competitive.
+
+                      "Product" means software that is offered to end users to manage
+                      in their own environments or offered as a service on a hosted
+                      basis.
+
+                      "Embedded" means including the source code or executable code
+                      from the Licensed Work in a competitive offering. "Embedded"
+                      also means packaging the competitive offering in such a way
+                      that the Licensed Work must be accessed or downloaded for the
+                      competitive offering to operate.
+
+                      Hosting or using the Licensed Work(s) for internal purposes
+                      within an organization is not considered a competitive
+                      offering. RADLAB LLC considers your organization to include all
+                      of your affiliates under common control.
+
+                      For binding interpretive guidance on using RADLAB LLC products
+                      under the Business Source License, please see the LICENSE_FAQ
+                      at https://github.com/getbourdon/bourdon/blob/main/LICENSE_FAQ.md
+Change Date:          Four years from the date the Licensed Work is published.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@bourdon.ai.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/LICENSE_FAQ.md

@@ -0,0 +1,79 @@
+# Bourdon License FAQ
+
+This document explains how the Business Source License (BSL) 1.1 applies to Bourdon. It is interpretive guidance — the [LICENSE](LICENSE) itself is the authoritative legal text.
+
+## TL;DR
+
+- **Free for almost everyone:** solo developers, internal use at any company, non-commercial projects, research, education
+- **Free for non-competing commercial use:** building a product on top of Bourdon that doesn't directly compete with RADLAB LLC's hosted Bourdon offering
+- **Requires a commercial license:** running Bourdon as a hosted/embedded service that competes with RADLAB LLC's paid offerings
+- **Auto-converts to Apache 2.0:** four years after each version is published, that version becomes pure Apache 2.0 (fully OSS forever)
+
+## Why BSL instead of MIT?
+
+Bourdon was originally MIT-licensed (v0.0.1 through v0.1.0). The rename from Continuo → Bourdon (2026-05-05) was the right moment to also relicense before the project gained external adoption — the project's strategy depends on RADLAB LLC capturing some commercial value to fund continued development. Pure MIT meant any cloud company could offer Bourdon-as-a-Service without contributing back, leaving the maintainer with no path to sustainability.
+
+BSL 1.1 keeps Bourdon source-available and free for the vast majority of users while preserving a commercial wedge against direct hosted-service competitors. HashiCorp (Terraform, Vault), CockroachDB, Sentry, Couchbase, and MariaDB all use this license; HashiCorp was acquired by IBM under BSL in 2024, demonstrating it doesn't kill commercial outcomes.
+
+## Common scenarios
+
+### ✅ I'm a developer using Bourdon to add memory to my own AI agent
+**Free.** Solo / internal use is explicitly permitted by the Additional Use Grant.
+
+### ✅ My company uses Bourdon internally for our own engineering tools
+**Free.** "Hosting or using the Licensed Work(s) for internal purposes within an organization is not considered a competitive offering."
+
+### ✅ I'm building a SaaS product that uses Bourdon under the hood
+**Probably free** — depends on whether your product is "competitive." If your product's main value is something else (e.g., a CRM that happens to use memory federation internally), you're fine. If your product *is* memory-federation-as-a-service marketed against Bourdon, you'd need a commercial license.
+
+The BSL Additional Use Grant defines "competitive offering" specifically: a product offered to third parties on a paid basis that *significantly overlaps with the capabilities of RADLAB LLC's paid version(s) of the Licensed Work*. If RADLAB LLC has no paid version yet, then there's nothing to overlap with — but a future paid version doesn't retroactively make existing non-competing products competitive (per the explicit grandfathering language in the grant).
+
+### ✅ I want to fork Bourdon and build a different memory system on top
+**Free**, as long as you're not running it as a competing hosted service. Standard OSS-style fork-and-modify is permitted.
+
+### ✅ I'm contributing back to Bourdon via a PR
+**Free.** Contribution doesn't trigger any commercial concerns.
+
+### ⚠️ I'm Anthropic / OpenAI / Google / a major AI vendor and want to integrate Bourdon natively into my product
+This is where you'd want to talk to RADLAB LLC. Native integration into a paid AI product *probably* counts as embedding under the BSL definition. A commercial license is straightforward to negotiate.
+
+Contact: licensing@bourdon.ai
+
+### ⚠️ I'm running a managed Bourdon hosted service for paying customers
+Commercial license needed. Same contact as above.
+
+## Auto-conversion timeline
+
+Each version of Bourdon auto-converts to **Apache License 2.0** four years after its first publication:
+
+| Version | Published | Apache 2.0 conversion |
+|---|---|---|
+| v0.2.0 | 2026-05-06 | 2030-05-06 |
+| v0.3.0 | 2026-05-09 | 2030-05-09 |
+| v0.4.0 | 2026-05-10 | 2030-05-10 |
+| v0.4.1 | 2026-05-10 | 2030-05-10 |
+| v0.5.0 | 2026-05-11 | 2030-05-11 |
+| v0.6.0 | 2026-05-11 | 2030-05-11 |
+| ... | ... | ... |
+
+After conversion, that version is fully OSS forever. The BSL only protects the *current* version; the long tail becomes Apache 2.0 over time.
+
+## What about old versions (v0.0.1 through v0.1.0)?
+
+Versions v0.0.1 through v0.1.0 were published under MIT. **Anyone who downloaded those versions has perpetual MIT rights to those specific releases.** Relicensing applies forward only, not backward — that's how OSS license changes always work.
+
+## Frequently confused points
+
+### "BSL isn't OSI-approved, so it's not 'real OSS'"
+True that BSL 1.1 isn't on the OSI-approved list, but it's source-available and auto-converts to Apache 2.0 (which IS OSI-approved). The OSS Initiative's narrow approval list is one definition of "open"; BSL meets a broader practical definition (code is public, can be read, modified, used freely for most purposes, and becomes OSI-approved over time).
+
+### "I can't use BSL code in my company because of policy bans"
+Some enterprise software policies are written against AGPL (a different copyleft license) and don't actually cover BSL. Worth checking with your legal team — most BSL projects have been accepted in environments that ban AGPL.
+
+### "What if I'm not sure whether my use is 'competitive'?"
+Email licensing@bourdon.ai with a description of what you're building. RADLAB LLC will give you a written interpretation. Better to ask than to guess.
+
+## Contact
+
+Licensing questions: **licensing@bourdon.ai**
+General project questions: GitHub issues at [github.com/getbourdon/bourdon/issues](https://github.com/getbourdon/bourdon/issues)

package/README.md

@@ -0,0 +1,61 @@
+# @getbourdon/participants
+
+The external-agent → L5 reader layer of [Bourdon](https://bourdon.ai) (BUSL-1.1).
+
+A **participant** normalizes a foreign agent's native memory store into a
+visibility-filtered, redacted [L5 manifest](../l5). It is the bridge between an
+agent's private, vendor-specific state and the cross-machine federation library.
+
+Python (`pip install bourdon`) is the oracle; this TS mirror asserts against the
+`@getbourdon/conformance` `native_stores` fixtures (output shape only).
+
+## Reader categories
+
+| Reader | Category | Native store |
+|---|---|---|
+| `HermesParticipant` | SQLite (read-only) | `~/.hermes/` — `state.db` sessions + `memories/*.md` |
+| `ClaudeCodeParticipant` | file / convention | claude-brain + `~/.claude/projects/*/memory/` + KG JSONL |
+| `GitHubCopilotParticipant` | network (TTL cache) | `api.github.com` PR activity → `~/.cache/bourdon/github-copilot/` |
+
+The heavier SQLite readers (`cursor`, `codex`, `copilot_cli`) are **deferred to
+the follow-on slice**; `openclaw` ships as the `@getbourdon/openclaw` plugin.
+
+## The four invariants (enforced in code, not by trust)
+
+1. **Visibility filter BEFORE emission** — every entity passes
+   `filterForFederation`; `private_tags` always win. A PRIVATE entity never lands
+   in a manifest.
+2. **Deterministic / idempotent `exportL5`** — same store → byte-identical
+   `toDict` (L6 hashes it for change detection).
+3. **`healthCheck` NEVER throws** — a diagnostic must never crash `bourdon doctor`.
+4. **Every native string through `@getbourdon/redaction`** before it enters L5.
+
+## Usage
+
+```ts
+import { discoverParticipants, toDict } from "@getbourdon/participants";
+
+for (const p of discoverParticipants()) {
+  const health = p.healthCheck(); // never throws
+  if (health.status === "blocked") continue;
+  const manifest = p.exportL5(); // visibility-filtered, redacted, deterministic
+  console.log(p.agentId, toDict(manifest));
+}
+```
+
+Discovery is a **static registry** (`FIRST_PARTY`), not a filesystem package
+scan — it preserves the Python oracle's `agentId`-sorted output, first-wins
+dedupe, and log-and-skip-on-construction-failure resilience. Third-party plugins
+are gated behind `BOURDON_PLUGINS=1` (a no-op stub today).
+
+## Native addon note
+
+The SQLite readers use [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3),
+a native addon. It is loaded lazily: if the addon fails to build on a given
+toolchain, `sqliteAvailable()` returns `false`, the SQLite readers degrade
+gracefully, and the rest of the package (file + network readers) keeps working.
+The SQLite-reader parity tests are gated on `sqliteAvailable()`.
+
+## License
+
+BUSL-1.1 — see [LICENSE](./LICENSE) and [LICENSE_FAQ.md](./LICENSE_FAQ.md).

package/dist/base.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Bourdon participant base — the Protocol → TS interface, errors, and the
+ * AgentStore / HealthStatus types. Faithful port of `participants/base.py`.
+ *
+ * The L5 dataclass model (AgentInfo/Entity/Session/VisibilityPolicy/L5Manifest),
+ * the `toDict` omission rules, and the visibility helpers all live in
+ * `@getbourdon/l5` and are reused verbatim — only THAT output shape is the parity
+ * contract. This module owns the participant CONTRACT surface around them.
+ *
+ * Contract semantics (enforced by every reader, asserted by the conformance
+ * fixtures, never by trust):
+ *   1. visibility filter BEFORE emission (`filterForFederation`) — private wins.
+ *   2. deterministic / idempotent `exportL5` — same store → identical `toDict`.
+ *   3. `healthCheck` NEVER throws — catch-all → degraded/blocked.
+ *   4. every native string through `@getbourdon/redaction` before it enters L5.
+ */
+import type { L5ManifestModel, SessionModel } from "@getbourdon/l5";
+/** Tied to Bourdon spec v0.1 — same literals as the Python oracle. */
+export declare const CONTRACT_VERSION = "0.1";
+export declare const SPEC_VERSION = "0.1";
+/** Base class for participant errors. */
+export declare class ParticipantError extends Error {
+    constructor(message?: string);
+}
+/** Raised by `discover()` when the native store cannot be found or read.
+ * Non-fatal: L6 skips this agent rather than aborting the whole export. */
+export declare class ParticipantDiscoveryError extends ParticipantError {
+}
+/** Raised by `exportL5()` / `exportSessions()` when an export fails mid-op
+ * (the store WAS present — distinct from a discovery miss). */
+export declare class ParticipantExportError extends ParticipantError {
+}
+/** Raised when the native store's version is outside the supported range.
+ * Subtype of discovery error (a version mismatch is a discovery-time miss). */
+export declare class ParticipantVersionMismatchError extends ParticipantDiscoveryError {
+}
+/** Metadata describing the native agent store. Returned by `discover()`. */
+export interface AgentStore {
+    path: string;
+    version: string;
+    metadata: Record<string, unknown>;
+}
+/** Returned by `healthCheck()`. Consumed by the `bourdon doctor` CLI. */
+export interface HealthStatus {
+    status: "ok" | "degraded" | "blocked";
+    reason?: string;
+    details: Record<string, unknown>;
+    /** A human-runnable command to remedy a non-ok status. */
+    proposedFix?: string;
+}
+/**
+ * Structural interface every participant must satisfy (the Python
+ * `@runtime_checkable Protocol`). Duck-typed at registration: a class is a
+ * participant iff it has `agentId` + `agentType` + `exportL5` + `healthCheck`.
+ *
+ * Optional members (`displayName`, a `defaultNativePath` static) are documented
+ * here as in the Python Protocol; discovery + the setup wizard fall back to
+ * sensible defaults when absent.
+ */
+export interface BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    nativePath: string;
+    /** Human-friendly label (e.g. "GitHub Copilot"). Optional. */
+    displayName?: string;
+    /** Confirm the native store exists; return metadata. Throws
+     * {@link ParticipantDiscoveryError} when missing/unreadable. */
+    discover(): AgentStore;
+    /** Build the L5 manifest from native memory, applying the visibility filter
+     * BEFORE return. Deterministic — same store yields the same manifest. */
+    exportL5(since?: Date): L5ManifestModel;
+    /** Export recent sessions in normalized schema. */
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    /** Return ok / degraded / blocked with a reason. MUST NOT throw. */
+    healthCheck(): HealthStatus;
+}
+/**
+ * Tiny structural guard mirroring Python's `_PARTICIPANT_MARKER_ATTRS`
+ * duck-type: a value is a participant iff it carries the four marker members.
+ */
+export declare function isParticipant(obj: unknown): obj is BourdonParticipant;

package/dist/base.js

@@ -0,0 +1,52 @@
+/**
+ * Bourdon participant base — the Protocol → TS interface, errors, and the
+ * AgentStore / HealthStatus types. Faithful port of `participants/base.py`.
+ *
+ * The L5 dataclass model (AgentInfo/Entity/Session/VisibilityPolicy/L5Manifest),
+ * the `toDict` omission rules, and the visibility helpers all live in
+ * `@getbourdon/l5` and are reused verbatim — only THAT output shape is the parity
+ * contract. This module owns the participant CONTRACT surface around them.
+ *
+ * Contract semantics (enforced by every reader, asserted by the conformance
+ * fixtures, never by trust):
+ *   1. visibility filter BEFORE emission (`filterForFederation`) — private wins.
+ *   2. deterministic / idempotent `exportL5` — same store → identical `toDict`.
+ *   3. `healthCheck` NEVER throws — catch-all → degraded/blocked.
+ *   4. every native string through `@getbourdon/redaction` before it enters L5.
+ */
+/** Tied to Bourdon spec v0.1 — same literals as the Python oracle. */
+export const CONTRACT_VERSION = "0.1";
+export const SPEC_VERSION = "0.1";
+// -- Errors -------------------------------------------------------------------
+/** Base class for participant errors. */
+export class ParticipantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Raised by `discover()` when the native store cannot be found or read.
+ * Non-fatal: L6 skips this agent rather than aborting the whole export. */
+export class ParticipantDiscoveryError extends ParticipantError {
+}
+/** Raised by `exportL5()` / `exportSessions()` when an export fails mid-op
+ * (the store WAS present — distinct from a discovery miss). */
+export class ParticipantExportError extends ParticipantError {
+}
+/** Raised when the native store's version is outside the supported range.
+ * Subtype of discovery error (a version mismatch is a discovery-time miss). */
+export class ParticipantVersionMismatchError extends ParticipantDiscoveryError {
+}
+/**
+ * Tiny structural guard mirroring Python's `_PARTICIPANT_MARKER_ATTRS`
+ * duck-type: a value is a participant iff it carries the four marker members.
+ */
+export function isParticipant(obj) {
+    if (obj === null || typeof obj !== "object")
+        return false;
+    const o = obj;
+    return (typeof o["agentId"] === "string" &&
+        typeof o["agentType"] === "string" &&
+        typeof o["exportL5"] === "function" &&
+        typeof o["healthCheck"] === "function");
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @getbourdon/participants — the external-agent → L5 reader layer (BUSL-1.1).
+ *
+ * Each participant normalizes a foreign agent's native memory store into a
+ * visibility-filtered, redacted L5 manifest. Three reader categories:
+ *   - SQLite (read-only, better-sqlite3 mode=ro): {@link HermesParticipant}
+ *   - file / convention:                          {@link ClaudeCodeParticipant}
+ *   - network (TTL cache + lazy AuthProvider):     {@link GitHubCopilotParticipant}
+ *
+ * Four invariants enforced in code, not by trust: visibility-filter-before-
+ * emission, deterministic exportL5, healthCheck never throws, redact every
+ * native string. Discovery is a static registry ({@link discoverParticipants}).
+ *
+ * Python (`pip install bourdon`) is the oracle; this mirror asserts against the
+ * @getbourdon/conformance `native_stores` fixtures (output shape only).
+ * Follow-on slice: cursor + codex (heavier SQLite) + copilot_cli; openclaw ships
+ * as the @getbourdon/openclaw plugin.
+ */
+export { CONTRACT_VERSION, SPEC_VERSION, ParticipantError, ParticipantDiscoveryError, ParticipantExportError, ParticipantVersionMismatchError, isParticipant, type AgentStore, type BourdonParticipant, type HealthStatus, } from "./base.js";
+export { sqliteAvailable, openReadonly, tryOpenReadonly, tableExists, tableColumns, epochToIsoDate, epochToIsoDatetime, projectKeyFromCwd, friendlyLabel, type OpenReadonlyOptions, type SqliteDatabase, } from "./sqlite-base.js";
+export { NETWORK_CONTRACT_VERSION, DEFAULT_CACHE_TTL_SECONDS, NetworkUnavailable, ParticipantAuthError, NetworkParticipant, PayloadCache, CacheEntry, envAuthProvider, defaultCacheRoot, type AuthProvider, type NetworkParticipantOptions, } from "./network-base.js";
+export { HermesParticipant } from "./readers/hermes.js";
+export { ClaudeCodeParticipant } from "./readers/claude-code.js";
+export { GitHubCopilotParticipant, ghTokenProvider } from "./readers/github-copilot.js";
+export { FIRST_PARTY, discoverParticipants, resolvePluginParticipants, type ParticipantCtor, } from "./registry.js";
+export { Visibility, applyVisibility, filterForFederation, toDict, validateManifest, type EntityModel, type L5ManifestModel, type SessionModel, type VisibilityPolicyModel, } from "@getbourdon/l5";

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @getbourdon/participants — the external-agent → L5 reader layer (BUSL-1.1).
+ *
+ * Each participant normalizes a foreign agent's native memory store into a
+ * visibility-filtered, redacted L5 manifest. Three reader categories:
+ *   - SQLite (read-only, better-sqlite3 mode=ro): {@link HermesParticipant}
+ *   - file / convention:                          {@link ClaudeCodeParticipant}
+ *   - network (TTL cache + lazy AuthProvider):     {@link GitHubCopilotParticipant}
+ *
+ * Four invariants enforced in code, not by trust: visibility-filter-before-
+ * emission, deterministic exportL5, healthCheck never throws, redact every
+ * native string. Discovery is a static registry ({@link discoverParticipants}).
+ *
+ * Python (`pip install bourdon`) is the oracle; this mirror asserts against the
+ * @getbourdon/conformance `native_stores` fixtures (output shape only).
+ * Follow-on slice: cursor + codex (heavier SQLite) + copilot_cli; openclaw ships
+ * as the @getbourdon/openclaw plugin.
+ */
+// Contract surface: Protocol interface, errors, AgentStore + HealthStatus.
+export { CONTRACT_VERSION, SPEC_VERSION, ParticipantError, ParticipantDiscoveryError, ParticipantExportError, ParticipantVersionMismatchError, isParticipant, } from "./base.js";
+// SQLite read-only primitives.
+export { sqliteAvailable, openReadonly, tryOpenReadonly, tableExists, tableColumns, epochToIsoDate, epochToIsoDatetime, projectKeyFromCwd, friendlyLabel, } from "./sqlite-base.js";
+// Network base: TTL cache, AuthProvider, degrade-to-stale-cache, auth boundary.
+export { NETWORK_CONTRACT_VERSION, DEFAULT_CACHE_TTL_SECONDS, NetworkUnavailable, ParticipantAuthError, NetworkParticipant, PayloadCache, CacheEntry, envAuthProvider, defaultCacheRoot, } from "./network-base.js";
+// Readers.
+export { HermesParticipant } from "./readers/hermes.js";
+export { ClaudeCodeParticipant } from "./readers/claude-code.js";
+export { GitHubCopilotParticipant, ghTokenProvider } from "./readers/github-copilot.js";
+// Discovery (static registry).
+export { FIRST_PARTY, discoverParticipants, resolvePluginParticipants, } from "./registry.js";
+// Re-exported from @getbourdon/l5 for convenience (the L5 model + serialization
+// the readers build on; only this output shape is the parity contract).
+export { Visibility, applyVisibility, filterForFederation, toDict, validateManifest, } from "@getbourdon/l5";

package/dist/network-base.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Network-shaped participant base — port of `participants/_network_base.py`
+ * (v0.3 adapter contract). Same `exportL5` / `exportSessions` half as a file
+ * participant; only the discovery half differs (fetch from an authenticated
+ * API). The base provides the three guarantees so adapters don't reimplement:
+ *
+ *   1. Local TTL cache under `~/.cache/bourdon/<slug>/payload.json` storing ONLY
+ *      `{fetched_at, payload}` — NEVER the token. A cache hit = zero network.
+ *   2. Graceful degradation: network down → serve the most recent cached payload
+ *      (even expired) and report `degraded` (not silence).
+ *   3. Auth boundary: an injected lazy {@link AuthProvider} (env / keychain).
+ *      An invalid token (401/403 non-ratelimit) ALWAYS propagates as `blocked`
+ *      and is NEVER masked by stale cache; a missing token serves stale when a
+ *      cache exists, else blocks; rate-limit degrades.
+ *
+ * A subclass sets `participantSlug` / `agentId` / `agentType` (+ `nativePath`)
+ * and implements `fetchPayload(token)` + `payloadToL5(payload)` (pure, no I/O).
+ */
+import type { L5ManifestModel, SessionModel } from "@getbourdon/l5";
+import { ParticipantError, type AgentStore, type BourdonParticipant, type HealthStatus } from "./base.js";
+export declare const NETWORK_CONTRACT_VERSION = "0.3";
+/** Default cache TTL — adapters override via `cacheTtlSeconds`. */
+export declare const DEFAULT_CACHE_TTL_SECONDS: number;
+/** Transport failure / timeout / 5xx / rate-limit — recoverable via cache fallback. */
+export declare class NetworkUnavailable extends ParticipantError {
+}
+/** 401/403 / missing credential — NOT recoverable via cache. The user must fix
+ * auth; surfaced as `blocked`, never silently served from stale cache (stale
+ * data would mask a broken token indefinitely). */
+export declare class ParticipantAuthError extends ParticipantError {
+}
+/** A zero-arg callable returning the token string, or null if no credential is
+ * available. Kept a callable (not a bare string) so the token is fetched lazily
+ * at call time and never sits in the participant's fields or the cache. */
+export type AuthProvider = () => string | null;
+/** Auth provider that reads a token from an environment variable. */
+export declare function envAuthProvider(varName: string): AuthProvider;
+/** `$XDG_CACHE_HOME/bourdon` or `~/.cache/bourdon`. */
+export declare function defaultCacheRoot(): string;
+/** A cached payload + the wall-clock time it was fetched (epoch seconds). */
+export declare class CacheEntry {
+    readonly fetchedAt: number;
+    readonly payload: Record<string, unknown>;
+    constructor(fetchedAt: number, payload: Record<string, unknown>);
+    get ageSeconds(): number;
+    isFresh(ttlSeconds: number): boolean;
+}
+/**
+ * A tiny JSON file cache, one file per participant slug. Stores only
+ * `{fetched_at, payload}` — never the auth token. Read/write are best-effort: a
+ * corrupt or unwritable cache degrades to "no cache", never raises.
+ */
+export declare class PayloadCache {
+    readonly slug: string;
+    readonly root: string;
+    readonly path: string;
+    constructor(slug: string, rootDir?: string);
+    read(): CacheEntry | null;
+    write(payload: Record<string, unknown>): void;
+}
+export interface NetworkParticipantOptions {
+    authProvider?: AuthProvider | null;
+    cacheRoot?: string;
+}
+/**
+ * Base for participants whose native state lives behind an authenticated API.
+ * Caching, degradation, the auth boundary, and the
+ * `discover`/`exportL5`/`exportSessions`/`healthCheck` plumbing live here;
+ * subclasses provide only `fetchPayload` + `payloadToL5`.
+ */
+export declare abstract class NetworkParticipant implements BourdonParticipant {
+    participantSlug: string;
+    agentId: string;
+    agentType: string;
+    cacheTtlSeconds: number;
+    nativePath: string;
+    protected readonly authProvider: AuthProvider | null;
+    private readonly cacheRoot?;
+    private cacheInstance?;
+    constructor(opts?: NetworkParticipantOptions);
+    /** Lazily built so it reads the SUBCLASS's `participantSlug` — subclass field
+     * initializers run after `super()`, so building the cache in the constructor
+     * would capture the base "network" slug instead. */
+    protected get cache(): PayloadCache;
+    /** Do the authenticated API call; return a JSON-serializable dict. Raise
+     * {@link NetworkUnavailable} on transport/5xx/rate-limit (→ cache fallback) or
+     * {@link ParticipantAuthError} on 401/403 (→ blocked, no fallback). */
+    abstract fetchPayload(token: string): Record<string, unknown>;
+    /** Normalize a (fresh or cached) payload into an L5 manifest. Pure, no I/O. */
+    abstract payloadToL5(payload: Record<string, unknown>): L5ManifestModel;
+    /**
+     * Resolve (payload, source) where source is 'cache' | 'network' | 'stale-cache'.
+     *   1. Fresh cache hit           → 'cache'        (no network)
+     *   2. Miss/expired + token      → 'network'      (fetch + refresh cache)
+     *   3. Net fails + any cache     → 'stale-cache'  (serve last good payload)
+     *   4. Net fails + no cache      → raise
+     * Auth errors are never swallowed — they propagate so health surfaces
+     * 'blocked' rather than serving stale data behind a dead token.
+     */
+    protected getPayload(): {
+        payload: Record<string, unknown>;
+        source: string;
+    };
+    discover(): AgentStore;
+    exportL5(_since?: Date): L5ManifestModel;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    healthCheck(): HealthStatus;
+}