> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Learning Core (developer)

# Learning Core (developer)

Internals and extension seams. For operating a deployment see
[Learning Core (admin)](https://docs.wednesdayai.dev/next/developers/plugins/learning-core-admin); for the feature itself see
[Learning Core](https://docs.wednesdayai.dev/next/developers/plugins/learning-core.md).

## Compatibility target

Bundled extension. Fork-base compatibility is expressed by the package SemVer and the `forkBase`
marker in `dist/build-info.json`, not by an `openclaw` peer range - bundled extensions carry no
`openclaw` peer dependency.

The Postgres backend uses a lazy `require("pg")` mirroring core's own pool construction, so no
runtime dependency is added to the extension package. A host without `pg` installed simply cannot
resolve to the Postgres backend.

## Module map

| Module | Owns |
| - | - |
| `lesson-record.ts` | Record kind, durability, validity window, schema version. |
| `lesson-store-factory.ts` | SQL backend selection, memoisation, and legacy read-through wrapping. |
| `lesson-store-sqlite.ts` | SQLite implementation of `LessonStore`. |
| `lesson-store-postgres.ts` | Postgres implementation plus the lazy pool. |
| `learning-schema.ts` | DDL for both SQL dialects; one of two schema-name checks (see below). |
| `learning-gate.ts` | The one fence-and-scope gate every learning writer and reader resolves its scope through. |
| `legacy-jsonl-readthrough.ts` | Read-only, bounded view of a pre-C0 log over a SQL store; SQL only after `repaired_at`. |
| `message-text.ts` | Pulling text out of stored transcript entries. |
| `extractor.ts` | `isCorrection` and `stripEnvelopeHeader`: anchor correction patterns and the envelope rule. |
| `capture-window.ts` | `buildCaptureWindow`: the cited, bounded message window the judge sees. |
| `extraction-candidate.ts` | `ExtractionCandidate` envelope (`record_type='candidate'`). |
| `learning-runner.ts` | Claim-path admission: write a candidate, not a lesson. |
| `promote-pass.ts` | `runPromotePass` — sole deterministic lesson writer. |
| `consolidation-pass.ts` | Budgeted LLM add/update/delete under the daily call ceiling. |
| `consolidation-judge.ts` | Judge v2: prompt version pin, verdict schema, input builder, and validation. |
| `learning-budget*.ts` | Candidate-claim fencing and the `learning_budget` ledger (SQLite, Postgres). |
| `distill-pass.ts` | LLM-authored pending SkillProposal per eligible lesson (HC10 name claim). Never writes `SKILL.md`. |
| `reconcile-skills-pass.ts` | Restores deleted or mutated applied files from `desiredState`. |
| `assist-collect.ts` | `context.collect` injection when `mode` is `assist`. |
| `gateway-methods.ts` | Read RPCs including `learning.searchLessons`. |
| `gateway-decide.ts` | `learning.decideProposal` and bulk `learning.decideProposals`. |
| `gateway-lesson-review.ts` | `learning.inspectLesson`, `learning.reviseLesson`, and `learning.rateLesson` (operator review). |
| `gateway-actor.ts` | The operator actor string for review audits: client name plus the paired device id. |
| `tool.ts` | The owner-gated `learning` agent tool. |

A schema name is validated at **both** SQL interpolation boundaries, not only in the DDL:
`resolveDomainStorage` checks it in core, `learning-schema.ts` checks it again when it builds the
DDL, and the `PostgresLessonStore` constructor checks it a third time. That last one matters
because a caller can construct the store directly and never touch the DDL path, so DDL-only
validation would be bypassable.

## Placement resolution lives in core

Backend selection lives in core and is exported from the plugin SDK:

```ts theme={"dark"}
import { resolveDomainStorage, type DomainStoragePlacement } from "wednesdayai/plugin-sdk";

const placement = resolveDomainStorage({ domain: "learning-core", config });
```

`DomainStoragePlacement` is a discriminated union:

```ts theme={"dark"}
type DomainStoragePlacement =
  | { backend: "postgres"; databaseUrl: string; schema: string }
  | { backend: "sqlite"; path: string };
```

The resolver is the **single** source of the selection rule. Do not re-derive "which backend"
inside a plugin - a second copy of the rule is exactly the drift this seam exists to prevent. Any
other plugin needing per-domain placement should call the same function with its own `domain`; the
default Postgres schema is derived as `plugin_<domain with dashes replaced by underscores>`.

## The `LessonStore` contract

One interface, two SQL implementations, one conformance suite. Members:

```text theme={"dark"}
Lessons     listLessons  getLesson  upsertLesson  insertLessonIfAbsent  mergeLesson
            supersedeLesson  invalidateLesson  listActiveLessons  listActiveLessonsPage
            getLessonsByIds  getLessonChain  searchLessons  countOverview
            legacyWindowTruncated? (optional)
Review      rateLesson  reviseLesson  listLessonExemplars
Proposals   listProposals  getProposal  findProposalWithScope  listProposalsWithScope
            insertProposalIfAbsent  upsertProposal  recordProposalDecision
Audit       appendAudit  listAudit
Candidates  upsertCandidate  insertCandidateIfAbsent  getCandidate  getCandidatesBySessionIds
            listPendingCandidates  listPendingCandidatesPage  markCandidateProcessed
            promotePendingCandidate
Claims      candidateClaimSupport  claimCandidate  renewClaim  releaseClaim  getLessonForClaim
            applyVerdict  recordCandidateFailure  recordCandidateNoOutputDay
Budget      consumeBudget  refundBudget  bucketProducer  pruneBudgetLedger  readBudgetUsage
Distill     listDistillCandidates  claimLessonForDistill  renewDistillClaim
            releaseDistillClaim  commitDistillProposal  recordDistillFailure
            recordDistillNoOutputDay
Backend     describeBackend  substrate
```

`invalidateLesson({ id, now, reason?, sessionId? })` ends a lesson's validity (sets
`invalidAt`) without writing a successor. It is idempotent: an already-invalid lesson is
returned unchanged. Inside a claim, a consolidation `delete` verdict without text applies the
same invalidation through `applyVerdict` (effect `invalidate`), in the transaction that
finalizes the candidate. Claim, budget, and distill operations are available on both SQL
backends; an unopened store reports `store_unavailable` rather than serving a file store.

The operator-review writers share the same locking discipline:

* `rateLesson({ id, rating, now })` holds the same effect lock as `invalidateLesson` and, in one
  transaction, writes the rating and the audit row (`lesson.endorsed` for `score: 1`,
  `lesson.retired` for `-1`). A -1 on an active lesson also retires it with
  `invalidationReason: "operator: <note|retired>"`. Endorsing a retired lesson is a domain
  error.
* `reviseLesson({ predecessorId, successor, actor, now })` supersedes in one transaction (the
  supersede effect locks held) and appends the `lesson.revised` audit row carrying the successor
  id.
* `listLessonExemplars({ limit })` projects rated or operator-authored lessons to compact
  `{ verdict: "good" | "bad", text, note? }` exemplars, newest update first. The consolidation
  pass injects them into the judge prompt as feedback; see [Judge v2](#judge-v2).

The provenance types behind these live in `types.ts`: `LessonOrigin` (producer
`consolidation | promote | operator`, time, rationale, model, prompt version, analysis job id,
actor), `LessonRating`, `EvidenceQuote` (a redacted cited message with `entryId`, `seq`,
`sender`), and `LessonExemplar`. `ExtractionCandidate` carries the capture `window`
(`CaptureMessage[]`) and the `anchor` index; `excerpt` remains the anchor text sliced to 500
characters for ranking, promote, and UI compatibility.

Candidates live in `learning_records` with `record_type='candidate'`. `listLessons` must not
return them. `searchLessons` returns lessons only.

**What not to do:**

```ts theme={"dark"}
// Do not invent a second table or overload record_kind.
await store.upsertLesson({ recordKind: "candidate", ...lesson });
```

```ts theme={"dark"}
await store.upsertCandidate(candidate); // record_type='candidate' in the same table
```

`describeBackend()` returns `{ backend, capability }`, surfaced by `learning.overview`.
The backend stays `sqlite` or `postgres`; an outage does not switch the implementation.

Adding a member means adding it to both SQL implementations, the legacy read-through wrapper,
and the conformance suite.

## Record lifecycle

`lesson-record.ts` is the only place that decides lifecycle shape:

```ts theme={"dark"}
export const LESSON_RECORD_KINDS = ["lesson", "skill"] as const;
export const LESSON_DURABILITIES = ["durable", "decaying", "ephemeral"] as const;
export const LESSON_SCHEMA_VERSION = 1;
```

* `withLessonDefaults` stamps a new record with the current defaults.
* `applyLegacyLessonDefaults` forward-migrates a pre-C0 record that predates these fields.
* `isLessonActive` evaluates `valid_from` and `invalid_at` against a supplied `now`. Callers pass
  the clock in; the function does not read it.

The extractor, fixtures, legacy read-through, and both SQL backends import from here. If you
find yourself writing a durability literal anywhere else, that is the defect.

**Supersede over delete.** `supersedeLesson` writes the successor, links `supersedes_id`, and
closes the predecessor's validity window. Nothing is removed. `getLessonChain` walks the links.
This is exposed through the `learning` tool, so the path has a production caller and is not
test-only code.

## Backend selection and failures

`createLessonStore` memoises by resolved location: SQLite databases by path, Postgres pools by
URL. `index.ts` builds a store at three call sites, so without memoisation the same file would be
opened three times and the same database pooled three times.

Neither reads nor writes fall back to files. The failure surfaces differ by backend:

* **SQLite** can fail at open. The factory logs the cause and returns an unavailable SQL store:
  data operations and claims report retryable `store_unavailable`, `substrate()` is undefined,
  and `describeBackend()` still identifies SQLite.
* **Postgres** does not connect at construction. A rejecting operation propagates its error;
  the store remains SQL-backed and the passes re-probe it on subsequent work.

The legacy JSONL read-through remains read-only for upgrades. It is not a second authoritative
store and is never substituted for a failed SQL operation.

## Fence-and-scope gate

`LearningGate` (`learning-gate.ts`) is the single place a learning entry point gets its scope:

* `resolve({ operation, access, agentId?, workspaceId?, workspaceDir? })` enforces, for writers
  (`access: "write"`), `store_unavailable` when SQL is configured but its substrate is missing,
  then `repair_pending` before `repaired_at`. A payload `workspaceId` must then equal the agent's
  local canonical id, and the local id must equal the recorded `canonical:<agentId>` row
  (`scope_mismatch`). All of that runs before anything is recorded. With no `agentId` it uses the
  default agent; it never guesses a workspace.
* Only a `write` that passed every check records a missing row (`scopes.claim`), and only for an
  agent this gateway configures (`listAgentIds`). Core resolves any other id to a default path,
  so an unconfigured agent with no recorded row fails closed with `agent_unconfigured`
  (`LEARNING_SCOPE_UNCONFIGURED`). Its reads and writes are refused, and nothing is recorded.
* `access: "read"` skips the fence (reads before `repaired_at` stay allowed). `read` and `preview`
  (dry runs) use `scopes.peek`, which compares against the recorded row and never records.
* `scopeRunnable(scope)` is the non-recording predicate for fan-outs. The maintenance pass, the
  startup sweep, and the idle trigger enqueue a scope only when it is its agent's canonical scope
  on this process. With no row recorded yet, the agent must also be configured here.
* `mismatchedAgents()` lists agents whose recorded id is not this process's. Cross-agent operator
  reads exclude their rows and report them as `mismatchedAgents`.

The standalone passes, `produce`, the `learning` tool, `learning.decideProposal`, the
`agent_end` sidecar, `context.collect`, session-end capture, and the operator read RPCs all go
through it. `recordCanonicalScope` runs under the fence lock.

A canonical row is recorded in two places only. The coordinator records one for each configured
agent while the fence is unrepaired (fence install). Otherwise the agent's first write records
it. Phase 4 records nothing and re-keys only agents that have a row. The pre-F rows of an agent
that no repairing gateway configured stay under their legacy key.

The first write of a gateway that configures such an agent records the row. It then calls
`rekeyAgentBatch` until none are left. Each call is one bounded transaction (200 rows) under the
fence lock, and it runs only after `repaired_at`. A claim before `repaired_at` (the coordinator
of a configuring gateway that starts mid-repair) records the row but is not remembered by
`LearningScopeResolver`, so the agent's next write re-runs the re-key idempotently. When
`runUpgradeFence` sees `repaired_at`, it also runs `rekeyRecordedAgents` (every recorded agent's
`rekeyAgentBatch` loop); a coordinator that starts after `repaired_at` runs it once too, in case
the repairing process stopped in between. It moves the rows with phase 4's `moveRecord`
collision rules:

* Lessons merge.
* Candidates keep the more final status.
* Proposals and audit rows keep both copies, the moved one under a scope-derived id.

## Reading transcript text

`extractMessageTextParts` is the seam that has bitten hardest. Production entries are
`StoredConversationEntry`, which has **no `content` field** - text lives in `contentText` and
`contentBlocks`. An extractor that reads only `content` yields zero candidates on every real
session while the claim path still acks `processed`, so the failure is completely silent.

Two rules follow:

1. Fixtures must use the real `StoredConversationEntry` shape. A `{ role, content }` fixture is a
   shape that never occurs in production and will pass while the code is dead.
2. Text arriving from storage carries a `[<from> <host> <timestamp>]` prefix, trailing space
   included. Correction patterns must account for it; a bare `^`-anchored regex can never match.

## Passes

Six built-in task passes. `registerTaskPass` takes the bare id; the backbone namespaces
it as `<pluginId>.<passId>`. Effective (namespaced) ids are stable — do not rename:

| effective id | stage | costClass | Writes |
| - | - | - | - |
| `learning-core.produce` | `deep` | `llm` or `deterministic` | The lesson producer the triggers enqueue (`produce-pass.ts`): runs the consolidation or the promote body, one producer per UTC bucket. Priority 110, consolidation's timeout and 14-attempt policy. |
| `learning-core.promote` | `light` | `deterministic` | Lessons from pending candidates whenever consolidation is not runnable (`runnable.ts`). Standalone and session-end inline use only; no candidate-state change at all while consolidation is runnable. |
| `learning-core.consolidation` | `deep` | `llm` or `deterministic` | Lessons under `maxCallsPerAgentPerDay` (default 8). Claim-fenced on both SQL backends. `llm` only when `consolidationStaticallyRunnable`. |
| `learning-core.distill` | `rem` | `llm` or `deterministic` | Pending SkillProposals only. `llm` only when `distillStaticallyRunnable`. |
| `learning-core.reconcile-skills` | `light` | `deterministic` | Restores `SKILL.md` from `desiredState`. With `distill.enabled`, its completion queues `distill` keyed by its own fingerprint. |
| `learning-core.maintenance` | `light` | `deterministic` | Daily global singleton (`maintenance:<utcDay>`): `learning_budget` retention by row kind, per-scope recovery items, and its own next-day successor. |

`TaskPass` shape is `{ id, stage?, priority, scope, costClass, timeoutMs?, run }`. There is no
`handler` field. `run` may return `{ successors }` (a `TaskPassResult`); the dispatcher inserts
them in the completion transaction. `produce` returns `reconcile-skills` (`<fingerprint>:reconcile`)
whenever its work item's lineage has a lesson effect, plus a continuation
(`<agent>:<workspace>:cont:<utcDay>:<spent>`) or a next-day carry
(`<agent>:<workspace>:carry:<nextUtcDay>`); distill's continuation is a successor too.

### Triggers and the producer bucket

`src/triggers.ts` holds the session-end handler and the `agent_idle` hook. The session-end
fingerprint is `<agentId>:<workspaceId>:<sessionId>`; the idle one is
`<agentId>:<workspaceId>:idle:<trigger>:<idleSinceMs+idleForMs>`, one per scope with pending
candidates. The handler takes no claim while the SQL store fails a live round-trip or the upgrade
fence is not repaired, captures with `insertCandidateIfAbsent`, then enqueues `produce` or runs
promote inline per the route table, and only then acks. It defers a claim
(`api.deferSessionWork`, attempt-neutral) instead of failing it when the store or recovery
admission fails after the claim, or when consolidation owns today's bucket. Store, enqueue and
busy-candidate deferrals retry after 60 seconds; scope or configuration deferrals retry after 24
hours, and a bucket owned by consolidation defers until the next UTC midnight. A
`session_not_visible` owner row (the `StorageReadAccessError` with
`retryable: true`) defers every 60 seconds while the claim is younger than 10 minutes measured
from `createdAt`, then fails retryable into the normal attempt budget; a
`session_foreign_owner` row is not-owned and acks non-retryable straight to `dlq`.

Every `applyVerdict` finalization is owner-fenced on the bucket `<agentId>:<utcDay>`: a verdict
with a reservation uses its charged day, anything else the database day. Inside the transaction
(`BEGIN IMMEDIATE` on SQLite, `pg_advisory_xact_lock` on the bucket key on Postgres) it
compare-and-sets the `owner:<agentId>:<utcDay>` row, sets its `has_effect` flag, writes the
per-item `effect:<producerTaskId>:<producerFingerprint>` row, and stamps the candidate's
`producer`, `producerTaskId`, `producerFingerprint`, and `producerBucket`. A mismatching producer
gets the domain error `LEARNING_PRODUCER_CONFLICT` and changes nothing. `produce` stamps the
namespaced task id `learning-core.produce` and the work item's trigger fingerprint, so a retry
finds its earlier effects even after midnight; the session-end inline promote uses
`learning-core.inline-promote` and `<agentId>:<workspaceId>:<sessionId>`.

The SQL-only surface behind this lives on `LessonStore.substrate()` (`learning-substrate.ts`;
`undefined` when the store could not open): the fence record and batches, canonical scope rows, bucket owner and
effect reads, keyset scope pages (`listScopesWithPendingCandidates`, distill, applied proposals),
and retention. Its procedures are generators over one SQL dialect kit (`learning-sql.ts`), driven
synchronously inside SQLite's `BEGIN IMMEDIATE` and asynchronously on one pinned Postgres client.

### Promote rules

`runPromotePass` is the deterministic producer. Its rules, in order:

* **Stand down while consolidation is runnable.** When `consolidationRunnable` is true, promote
  makes no candidate-state change at all, not even the untagged skip. `previewPromotePass`
  (dry run) reports `consolidation_runnable`.
* **Skip consolidation's buckets.** On SQL stores, candidates whose agent's current UTC bucket
  consolidation already owns are left pending (`ownedByConsolidation` in the summary).
* **Skip untagged candidates.** A candidate tagged only `untagged` is finalized as `skipped`,
  so bland sessions do not pile up.
* **Group and threshold.** Other candidates become draft lessons and are grouped by lesson id,
  workspace, and agent. A group is merged only when the accumulated lesson (existing lesson plus
  drafts) clears `minConfidence` and `minOccurrencesWithCorrection` (corrections) or
  `minOccurrences` (others), plus two distinct sessions when `requireDistinctSessions` is on.
  Groups below the threshold stay pending (`belowThreshold`).
* **Claim the whole group.** On SQL every candidate of a group is claimed first; a partially
  claimed group waits for the next run. A candidate held by another live run makes the run fail
  with the retryable `candidates busy` error after it finishes the rest.
* **Owner fence.** Each finalization goes through `applyVerdict` with producer `promote`; a
  `producer_conflict` stands the run down with its claims released and nothing applied.

### Judge v2

The consolidation judge's system prompt is pinned by `JUDGE_PROMPT_VERSION`
(`judge-v2:<first 12 hex chars of its SHA-256>`), so a lesson's `origin.promptVersion` names the
exact prompt that produced it. `buildJudgeInput` emits
`{ window, anchor, tags, similarLessons, examples }`: the candidate's capture window (or, for a
pre-v2 candidate without one, a single-message window built from `excerpt`), up to
`JUDGE_SIMILAR_K` (5) similar active lessons, and up to `JUDGE_EXEMPLARS_MAX` (6) operator
exemplars from `listLessonExemplars`. The consolidation pass loads the exemplars once per run.
`rankSimilarLessons` scores active lessons by distinctive-token overlap with the candidate excerpt
and shows the top `JUDGE_SIMILAR_K` (5). Lessons with no shared token still fill any free slots,
and ties go to the newest lesson (the ranking pool is read in `created_at` order), so a
contradicting lesson that shares no words with the candidate can reach the judge.

`validateJudgeVerdict(value, allowedLessonIds, window)` keeps the base checks (`action` enum,
`confidence` in \[0, 1], `reason` string, `lessonId` in `allowedLessonIds`) and adds the v2 rules:

* `add`/`update`: non-empty `text` of at most `JUDGE_TEXT_MAX_CHARS` (400) characters, `kind` in
  `JUDGE_KINDS` (`correction`, `preference`, `procedure`, `failure`), and `sourceIndexes` — a
  non-empty integer array with every index inside the window and at least one pointing at a
  `user` message.
* `delete`: the same `sourceIndexes` rule; `kind` is required whenever `text` is given.
* `noop`: `rejectCategory` in `JUDGE_REJECT_CATEGORIES` (`fact`, `one_off`, `automated`,
  `transient_failure`, `already_known`, `no_signal`).

Any violation returns `{ ok: false, error }`, which classifies as `invalid` and is struck against
the candidate by the existing failure mechanism. Judge calls are capped at `JUDGE_MAX_OUTPUT_TOKENS`
(8,192).

On an applied verdict the effect layer (`consolidation-effects.ts`) writes `origin`
(`producer: "consolidation"`, the redacted judge `reason` as `rationale`, the
`${provider}/${model}` from the analysis result, the prompt version, and the analysis job id),
sets the lesson `kind` from the verdict instead of the candidate tags, and stores the cited
messages as `evidence[].quotes` — the first three cited window messages as `EvidenceQuote`
entries (text sliced to 500), the primary quote being the first user-role one. The invalidate
path stores the redacted judge reason as `invalidationReason`. `promote` marks its lessons
`origin.producer: "promote"`.

### Consolidation and produce execution

`runConsolidationPass` accepts `RunConsolidationPassParams`, including optional
`capPreflight?: { agentId: string; utcDay: string }`. When present, the pass pre-flights the daily
budget against `store.readBudgetUsage({ pass: "consolidation", agentId })`:

* **Cap preflight.** If `usage.utcDay === preflight.utcDay` and `usage.spent >= maxCallsPerAgentPerDay`,
  the run stands down before judging: it makes no model call, claims no candidates for judging, and
  writes no `learning_budget` reservation row. The run records `capExhausted: true` in
  `ConsolidationRunSummary`, sets `budgetSkipped = selected.length`, and immediately runs the
  deterministic expiry sweep (`expireUnsampled`, finalizing untagged candidates as `not_sampled_expired`).
  If `preflight.utcDay` is not today, the gate stays off and per-candidate reservation remains the
  authority. The standalone `learning-core.consolidation` pass provides no `capPreflight`.
* **Deterministic candidate selection.** `pickCandidates` partitions candidates deterministically:
  correction and contradiction candidates rank ahead of plain failures, followed by remaining tagged
  candidates, then untagged candidates. Each group is sorted newest first (`endedAt` descending), so
  the oldest untagged candidates are the ones that expire.
* **Produce integration.** `ProduceBodies.consolidation` receives
  `{ producerTaskId, producerFingerprint, budgetDay, onReport }`, where `budgetDay` is the lineage's
  pinned reservation day, else today; the plugin's produce body forwards it as
  `capPreflight.utcDay`. A capped produce run records `items.capExhausted: true`; when it finalized
  nothing it also records `producerReason: "cap_exhausted"`, which the `tasks.runEvents` allowlist
  in `src/gateway/server-methods/tasks-run-events.ts` surfaces. With claimable candidates left, the
  run queues the usual next-day carry.

### Distill eligibility

`listDistillCandidates` decides eligibility in SQL: only `procedure` or `failure` lessons with at
least 2 occurrences, or a `+1` rating, or `origin.producer: "operator"`, are selected.
Single-occurrence, unrated lessons of any other kind are never distilled.

### Candidate claims and the budget ledger

`consolidation` and `promote` never apply a candidate without a claim. The order is:
`claimCandidate` → `renewClaim` → `consumeBudget` → model call → `renewClaim` → `applyVerdict`.

* `claimCandidate` is a compare-and-set from `pending` with no unexpired claim. The lease is the
  call timeout plus 30 s, judged on the database clock.
* `applyVerdict`, `recordCandidateFailure`, `renewClaim`, and `releaseClaim` all check
  `status = 'pending'` and the same `claimId`. A stale claimant gets `stale` and changes nothing.
* `applyVerdict` writes the lesson effect and finalizes the candidate in one transaction. A replay
  of the same claim returns `already_applied`. A supersede whose predecessor already has a
  different successor is refused.
* `consumeBudget` and `refundBudget` run in one transaction each (`BEGIN IMMEDIATE` on SQLite,
  `pg_advisory_xact_lock` on Postgres). Denied consumes are recorded, so a retried reservation id
  always returns its first decision. A refund credits the day the reservation charged.
* Claims, capture, budgets, lessons, proposals, and audit writes all require SQL. No operation
  is replayed on a file fallback when the database fails.
* Both producers key the producer bucket by the candidate **row's** agent (the claim handle's
  `agentId`, `bucketAgentId`). `applyVerdict` refuses any other `ownerBucket`, and an agent-less
  row is released rather than finalized.
* Before the upgrade fence's `repaired_at`, every SQL learning writer throws the retryable
  `LEARNING_REPAIR_PENDING`; the fence batches live in `upgrade-fence.ts` and
  `upgrade-fence-sql.ts`.
* Fence phases 2 and 3 read the legacy source recorded at install (`meta:legacy-source`: files
  relative to the plugin log dir, each with its size and SHA-256). The cursor stores a relative
  file and an offset in that source. A process whose `legacySourceMatches` is false stands by
  (`fence_source_mismatch`, `onSourceMismatch`), and `fenceStep` itself refuses a step whose
  `sourceDigest` is not the recorded one or whose `next` is not after `from`.

Run the real-Postgres contention tests with `pnpm test:pg`. The script starts a Docker
`postgres:16` container unless `OPENCLAW_DATABASE_URL` is set.

Apply writes under `resolveManagedSkillsDir()` → `$OPENCLAW_STATE_DIR/skills` or
`~/.openclaw/skills`. The protocol is hash-verified tmp + `fsync` + rename. After a successful
rename, a later decision-write failure must not delete the file; reconcile repairs `desiredState`.

`searchLessons(query, identity, k)` uses FTS5 (sqlite), `search_tsv` + GIN (postgres), or a
substring scan when optional search DDL is skipped. Hyphenated FTS5 queries are
tokenized because hyphen is FTS `NOT`.

## Gateway and tool seams

Ten gateway methods are registered in `index.ts`: `learning.overview`, `learning.listLessons`,
`learning.searchLessons`, `learning.inspectLesson`, `learning.listProposals`,
`learning.inspectProposal`, `learning.decideProposal`, `learning.decideProposals`,
`learning.reviseLesson`, and `learning.rateLesson`. The read path goes **through the
store**, not the raw log. This matters: leaving the read path on the JSONL log while capture moved
to SQL would show an empty list while capture silently succeeded.

The three review RPCs (`gateway-lesson-review.ts`) resolve one lesson the same way
`inspectProposal` does: `params.agentId` narrows to that agent's verified scope, a cross-agent
read hides mismatched agents' rows, and an id that resolves to more than one visible scope is
refused as ambiguous. `learning.inspectLesson` needs the read scope and returns the lesson detail
(origin, rating, invalidation reason, evidence with quotes), the revision chain, and the
proposals built from the lesson. `learning.reviseLesson` (text ≤400, optional `kind`, optional
`note` ≤500) and `learning.rateLesson` (`score: 1 | -1`, optional `note`) need the approvals
scope; the write gates the lesson's own scope exactly like decide, then calls
`store.reviseLesson` / `store.rateLesson`. The audit actor comes from `operatorActor`
(`gateway-actor.ts`): the client display name plus the paired device id when one is present.
`learning.listLessons` rows carry `producer` and `rating` so the UI can badge operator edits and
endorsements.

`learning.decideProposal` looks a proposal up with an empty scope deliberately, so the lookup spans
every workspace and the proposal's own scope comes back in the result. It then gates that scope
(`scope_mismatch` unless it is the proposal agent's verified scope) and builds a scoped store from
it for the write. `learning.decideProposals` keeps the pre-fence contract: ids are decided in
order and the batch stops at the first failure with `UNAVAILABLE` `failed to decide`, whose
`details` name the failing id, its gate `reason`, and the `decided` and `notAttempted` ids.

`learning.listLessons` reads the optional `LessonStore.legacyWindowTruncated()` (the legacy
read-through implements it) and reports `truncated` when the pre-repair legacy window was cut.
`learning.searchLessons` filters mismatched agents after the store's top-k, so it over-fetches
(x4 per round, at most 1,000 candidates) until `k` visible hits survive.

The `learning` tool is registered per invocation with the caller's scope and owner flag. Every
action is refused unless `senderIsOwner` is true.

## Glance widget

`createLearningGlanceWidget` registers a glance widget (id `learning`, title `Learning`,
`refreshMs: 300_000`) via `api.registerGlanceWidget`. Its `render` calls the same
`computeLearningOverview` aggregate as `learning.overview` with no scope filter, and returns three
lines — `pending` proposals, total `lessons`, `applied` proposals — pulled by glass clients through
`glance.widgets.list` (ADR 0107). It never mutates the store.

## Capture path

Learning Core is a session consumer. `onSessionWorkAvailable` filters to `session.end`, then loops
`claimSessionWork` until the queue drains. When `mode` is `off`, the handler acknowledges without
persisting. Otherwise it builds the capture window (`buildCaptureWindow`,
`capture-window.ts`) from the claimed entries: user and assistant entries only -
`isAutomated: true` drops heartbeat, cron and subagent turns, and a legacy `undefined` counts as
human - each text envelope-stripped (user messages), redacted, and sliced to
`CAPTURE_MESSAGE_MAX_CHARS` (800). The anchor is the last user message matching `isCorrection`,
else the last user message; the window holds at most `CAPTURE_WINDOW_MAX_MESSAGES` (12) messages
ending one message past the anchor and is trimmed to `CAPTURE_WINDOW_MAX_CHARS` (4,000) by
dropping the oldest non-anchor messages. When no user message remains the runner returns `none`,
the claim is acked without a candidate, and no `produce` pass is enqueued - automation-only
sessions capture nothing. When a window exists the runner writes an `ExtractionCandidate`
carrying it (`window`, `anchor`, `excerpt` = the anchor text sliced to 500 characters, tags)
and acks `processed`. It must not call `upsertLesson` / `mergeLesson`. On a processing failure
the catch block logs `api.logger.warn` (message, error code, claim and session IDs) **before**
acking the claim as failed/retryable — a throwing `ackSessionWork` must never mask the real
error.

Core namespaces consumer ids as `<agentId>:<pluginId>:<effectKind>`, with an unscoped
`<pluginId>:<effectKind>` fallback and an optional `/<subCursor>` suffix. Anything that **counts
or looks up** claims must match all those shapes - an equality against a bare `learning-core`
matches nothing.

When `mode` is `assist`, `register` also listens for `context.collect` and prepends
`ctx:{sessionKey}:lessons.active` with up to `maxLessonsForPrompt` active lessons
(`collectActiveLessons`, `assist-collect.ts`). Do not import context-engine from this plugin.

* **Trigger gate.** Heartbeat and cron turns (`isAutomatedTrigger`) return before the session
  check, so automated turns never inject lessons and never read the lesson store.
* **Host OS.** A lesson may carry `hostOs` (`"linux"`, `"darwin"` or `"win32"`, the
  `process.platform` value). The consolidation judge sets it only when the lesson names one
  system's commands, paths or service managers; a rewrite without it clears it. Lessons scoped to
  another OS are filtered out before ranking, so they never use a `maxLessonsForPrompt` slot.
  Untagged lessons inject on every host.
* **Wrapper.** The lessons reach the model as one block, each lesson on a dash (`-`) line under the
  shared `ASSIST_LESSONS_HEADER`, which marks them advisory and subordinate to the current user
  message, the workspace instructions and the operator's rules:

  ```text theme={"dark"}
  <injected-context source="learning-core" kind="lessons">
  Lessons learned from earlier conversations. They are advisory: the current user message, the workspace instructions and the operator's rules take precedence.
  - Prefer HTTPS
  </injected-context>
  ```

## Blocking the agent loop

`register` is synchronous today. Do not add synchronous blocking I/O (`fs.readFileSync`,
`execSync`) inside it — that stalls gateway startup. Pass `run` functions are async and must not
block the event loop on LLM or disk work without `await`.

**Do not do this:**

```ts theme={"dark"}
export default function register(api: OpenClawPluginApi): void {
  const raw = fs.readFileSync("./lessons.json", "utf8");
  api.registerTaskPass({ id: "promote", run: () => JSON.parse(raw) });
}
```

A dotted pass id (`"learning-core.promote"`) throws `PLUGIN_REGISTER_ERROR` at Gateway boot
(`Plugin task pass id must not contain "."`). Register the bare id (`promote`); the backbone
stores the effective id `learning-core.promote`.

**Do this instead:**

```ts theme={"dark"}
export default function register(api: OpenClawPluginApi): void {
  api.registerTaskPass({
    id: "promote",
    stage: "light",
    priority: 50,
    scope: "agent",
    costClass: "deterministic",
    run: async () => {
      await runPromotePass({ store, cfg, now: new Date().toISOString() });
    },
  });
}
```

## Testing

| Suite | Proves |
| - | - |
| `lesson-store-conformance.test.ts` | Both SQL backends satisfy the same contract. |
| `claim-to-store.reachability.test.ts` | A `session.end` claim lands exactly one candidate (not a lesson) and acks `processed`. |
| `capture-window.test.ts` | The window drops automated turns, anchors the correction, and honours the budgets. |
| `lesson-store-factory.test.ts` | SQL selection, memoisation, unavailable-store errors, and legacy read-through. |
| `workspace-scope.reachability.test.ts` | Two gateways on one DB: the mismatched one fails closed on every entry point. |
| `session-end-unconfigured.reachability.test.ts` | An unconfigured agent's claim is deferred daily; the drain still captures the others. |
| `lesson-store-postgres.test.ts` | Refusal paths, transaction rollback, and the legacy-id migration branch. |
| `learning-schema.test.ts` | DDL for both dialects; schema-name rejection. |
| `legacy-jsonl-readthrough.test.ts` | Read-only folding, SQL-wins precedence, proposals excluded. |
| `legacy-readthrough-bounded.conformance.test.ts` | A large legacy log: bounded bytes and heap before and after `repaired_at`. |
| `message-text.test.ts` | Extraction against the real stored-entry shape. |

The conformance suites' live-Postgres legs, `lesson-store-conformance.pg.integration.test.ts` and
`bounded-store-reads.pg.integration.test.ts`, run only in `pnpm test:pg`. The default lanes do not
collect them, and without that lane's database they report as skipped (`describe.skipIf`) rather
than passing. The conformance suite carries a mutation self-check so a suite that cannot fail is
itself a failure.

**Live golden set.** `consolidation-judge.live.test.ts` judges ten synthetic windows against the
real configured tier and asserts each fixture's expected action, kind, or reject category. It is
collected only by the live config and skipped unless `OPENCLAW_LIVE_TEST=1` and
`OPENCLAW_LIVE_LEARNING_BASE_URL` are set; `pnpm test:live` already sets `OPENCLAW_LIVE_TEST=1`:

```bash theme={"dark"}
OPENCLAW_LIVE_LEARNING_BASE_URL=http://<judge-host>:<port>/v1 \
OPENCLAW_LIVE_LEARNING_MODEL=low \
OPENCLAW_LIVE_LEARNING_API_KEY="$KEY" \
pnpm test:live extensions/learning-core/src/consolidation-judge.live.test.ts
```

`OPENCLAW_LIVE_LEARNING_MODEL` defaults to `low`; `OPENCLAW_LIVE_LEARNING_API_KEY`, when set, is
sent as a bearer token. The fixtures are synthetic; never point the test at a real transcript
store.

### Running the Postgres store without a Postgres server

`lesson-store-postgres.test-helpers.ts` provides `createInMemoryPgPool()`, a `PgPoolLike` double
covering the six statement shapes `PostgresLessonStore` emits. It keeps the fidelity the store
depends on - JSONB decoded on read, the four-column primary key, transaction visibility, and an
error rather than an empty result when a table was never created - and **throws on any statement it
does not recognise**, so a store that grows a new statement shape fails loudly instead of passing
against a silent no-op.

The conformance suite runs the Postgres store twice: against this double on every host, and against
a live server in `pnpm test:pg`. The double is not a substitute for the live leg, which remains the
authority on real dialect behaviour.

The reachability suite exists because unit coverage of the changed function proves the unit, not
that it is reached. It drives the real claim entry point and asserts the symptom - one candidate
row per claim, zero lessons - rather than an internal return value.

Run the extension's tests with the standard battery; there is no separate learning-core lane. Its
`*.pg.integration.test.ts` suites run only with `pnpm test:pg`.

## Adding a backend

1. Implement `LessonStore`.
2. Add the dialect to `learning-schema.ts` if it is SQL, keeping identifier validation in that
   module.
3. Add the backend to the union in `src/config/storage/domain-storage.ts` and to
   `SessionStorageBackendKind`, so selection stays in one place.
4. Add it to `BACKENDS` in the conformance suite and make the suite pass unmodified.
5. Surface open-time and operation failures without changing the authoritative backend.

## Related

* [Learning Core](https://docs.wednesdayai.dev/next/developers/plugins/learning-core.md)
* [Learning Core (admin)](https://docs.wednesdayai.dev/next/developers/plugins/learning-core-admin)
* [Plugin manifest](https://docs.wednesdayai.dev/next/developers/plugins/manifest.md)
* [Session consumer claims](https://docs.wednesdayai.dev/next/developers/plugins/session-consumer-claims.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.