Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/adr/0001-learning-extension-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Status: proposed on October 6, 2026, and revised on October 10, 2026 to follow the requirements the Replica maintainers agreed on. Needs review by the Replica maintainers.

The learning package, providers, CLI, and demos still work. Hub descriptions below record an earlier proposal, not what the [new Hub](../../hub/README.md) can do today. It does not collect comments, run learning jobs, store learning data, sign people in, or connect Copilot. Adding those features requires separate product and architecture decisions.
The learning package, providers, CLI, and demos implement this architecture. The [new Hub](../../hub/README.md) now stores review conversations, captures complete repository snapshots, connects Copilot, runs explicit learning jobs, records decisions, recalls accepted guidance, and redacts deleted comment text. Daily change-driven discovery remains separate work.

## Context

Expand Down Expand Up @@ -96,9 +96,9 @@ Each import records whether every list page and reply page was present. The impo

### Integration with Hub

The earlier proposal had Hub run `replica-learning` for every step, so the package's rules applied throughout. It kept one store per repository outside any checkout. A background job imported review comments, removed deleted text, labeled new or edited comments, and proposed learnings. Administrators reviewed proposals, and the plugin read accepted learnings. The [new Hub](../../hub/README.md) does not run these steps.
Hub runs `replica-learning` for every step, so the package's rules apply throughout. It keeps one store per repository outside any checkout. An explicit background job imports review comments, removes deleted text, labels new or edited comments, and proposes learnings. Administrators review proposals, and recall returns accepted learnings for agents.

The package can label through the [Copilot SDK](https://github.com/github/copilot-sdk). Its session has no tools, refuses every permission request, and never sees who wrote a comment. Copilot chooses the model unless the store's configuration names one, and each run records the usage Copilot reports. The new Hub does not set up or authorize this connection.
The package can label through the [Copilot SDK](https://github.com/github/copilot-sdk). Its session has no tools, refuses every permission request, treats comment text as untrusted data rather than instructions, and never sees who wrote a comment. Copilot chooses the model unless the store's configuration names one, and each run records the usage Copilot reports. Hub supplies only a currently usable configured credential.

The command still runs in a checkout, with data under `.replica/learning/`, for contributors and for other hosts. This complements #230: its discovery output can become labels, and its judge can become a consolidator.

Expand Down
4 changes: 2 additions & 2 deletions hub/docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The [Pino integration](logging.md) writes structured application and HTTP logs t

The [prototype details editor](frontend.md#prototype-metadata-edits) lets signed-in members edit visible prototypes and register drafts. Hub holds session authority and prototype visibility locks through the write and detail read-back.

The [background-job foundation](background-jobs.md) uses BullMQ with PostgreSQL and separate on-demand and scheduled worker processes. Setup migrates BullMQ's own schema independently of Prisma. Product processors and schedules are not registered yet.
The [background-job foundation](background-jobs.md) uses BullMQ with PostgreSQL and separate on-demand and scheduled worker processes. Setup migrates BullMQ's own schema independently of Prisma. Learnings registers on-demand run and redaction processors plus one scheduled recovery sweep.

The [artifact storage domain](artifact-storage.md) selects filesystem or managed-identity Azure Blob storage behind one immutable-byte contract. Future product domains call this provider-neutral API, not SDK integrations directly. Startup validates explicitly configured storage, but no product route or processor consumes artifact bytes yet.

Expand All @@ -46,7 +46,7 @@ The administrator session-revocation API and retained frontend show current Hub

The deployment-wide Copilot connection API and retained `/settings/copilot` frontend require a live administrator session. Hub obtains a credential from the configured provider and verifies it through the separate `replica-learning` process, then locks the persistent connection generation and rereads authority before committing the connection and typed security audit together. The database stores the provider key and configuration digest, never the credential.

The [learning foundation](learning-foundation.md) validates private storage, isolates the command's environment and temporary state, bounds output and execution time, and provides a PostgreSQL execution lock plus repository-store preparation primitive. The [review backend](review-collaboration.md) now provides complete repository snapshots with stable actors, deleted-message markers, and ordered resolution history. Learning import, runs, decisions, redaction execution, and recall remain unimplemented.
The [learning foundation](learning-foundation.md) validates private storage, isolates the command's environment and temporary state, bounds output and execution time, and provides a PostgreSQL execution lock plus repository-store preparation primitive. The repository API reads exact review evidence, accepted guidance, recall, and persisted run history; records accept, edit, reject, and retire decisions through the package store; and queues explicit runs. Workers import complete [review backend](review-collaboration.md) snapshots, label and consolidate within fixed bounds, preserve usage and failures, and redact deleted comment text.

## Frontend

Expand Down
2 changes: 1 addition & 1 deletion hub/docs/background-jobs.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Each command starts one Node.js process consuming only its assigned queue. The A

`ON_DEMAND_JOB_CONCURRENCY` and `SCHEDULED_JOB_CONCURRENCY` independently set the number of active jobs per worker process. Both default to one and accept integers from 1 through 100. CPU-heavy JavaScript still blocks that worker's event loop; move that work to a subprocess or an appropriate execution boundary when adding the domain.

`server/workers/configuration.ts` is the composition point for processors and schedules. Its empty registrations are intentional until product domains exist. Worker startup logs readiness after connecting; unknown job names fail permanently rather than disappearing.
`server/workers/configuration.ts` is the composition point for processors and schedules. Learnings registers explicit run and review-comment redaction work on `on-demand`. A one-minute scheduled recovery sweep re-enqueues queued runs and deleted-comment redactions with stable job IDs. Worker startup logs readiness after connecting; unknown job names fail permanently rather than disappearing.

Worker readiness confirms initial connection only; it is not continuous consumer-health monitoring. A later connection error is logged but does not clear the combined runtime's worker-initialized signal.

Expand Down
2 changes: 1 addition & 1 deletion hub/docs/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ Errors use an HTTP status and `{ "error": "..." }`. Request schemas and the same

The [product contracts](../client/application/hub/product-contracts/index.ts), [Learnings contracts](../client/application/hub/learnings-contracts/index.ts), [settings contracts](../client/application/hub/settings-contracts/index.ts), and [session contracts](../client/application/hub/session-contracts/index.ts) define those provisional records. The review adapter injects this request boundary into the retained review hooks without changing their default consumers. Persona selection, scenarios, diagnostics, fixture generation, and local mutation rules belong to the mock runtime, not these contracts.

The Learnings backend still needs all three listed endpoints. Its read response must make repository authorization authoritative, return access denial without suggestion or evidence data, distinguish Hub-wide Copilot connection state from repository decision permission, and return exact review digests, replacement targets, evidence and contradiction counts, accepted-learning integrity states, recall text, recent run results, and decimal AI-credit usage. Decision writes must reject a stale digest and validate decision-specific fields. Run and decision writes must reread repository-administrator authority and return visible `403`, `409`, or `422` errors rather than success-shaped empty data. The local handlers keep only tab-lifetime development state and do not provide persistence, jobs, repository discovery, review import, or Copilot execution.
The Learnings backend implements all three listed endpoints. Its read response makes current authorization authoritative, returns access denial without suggestion or evidence data, distinguishes Hub-wide Copilot connection state from decision permission, and returns exact repository evidence, accepted-learning integrity states, recall text, recent persisted run results, and decimal AI-credit usage. Decision writes validate decision-specific fields, invoke the package store, reject stale review digests with `409`, and record typed security audits. Run and decision writes reread current administrator authority. A run request captures and digests one complete repeatable-read review snapshot before it creates and queues a run; a changed, incomplete, or unavailable snapshot fails visibly rather than producing a no-op success.

## Removing mocks

Expand Down
40 changes: 26 additions & 14 deletions hub/docs/learning-foundation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Learning foundation

Hub can persist one deployment-wide Copilot connection and run the host-neutral [`replica-learning`](../../packages/learning/README.md) command through a bounded process boundary. The review backend can capture one complete repository snapshot, but learning imports, runs, decisions, redactions, and recalls are not connected yet.
Hub can persist one deployment-wide Copilot connection and run the host-neutral [`replica-learning`](../../packages/learning/README.md) command through a bounded process boundary. The repository Learnings API reads exact evidence, accepted guidance, recall previews, and persisted run history; records accept, edit, reject, and retire decisions; and queues explicit runs. Workers import complete review snapshots, label and consolidate them, and redact deleted comment text.

The package remains the authority for consent, purpose, evidence, approval, redaction, and learning lifecycle rules. Hub does not reimplement those rules.

Expand All @@ -22,9 +22,9 @@ Disconnecting removes the connection record and advances the generation. It does

`REPLICA_LEARNING_ROOT` defaults to `storage/learning`. It must be a dedicated directory outside every configured static-file root. Hub rejects the filesystem root, the Hub application root, the shared `storage` root, the source public directory, the configured built-client directory and their descendants, files, and paths containing symbolic links. The check runs at startup and again when a repository store is prepared.

A future repository learning integration supplies the persisted repository UUID and package scope such as `github.com/repositories/123`. The store primitive creates `<root>/repositories/<repository-uuid>` with mode `0700` and writes the package's default `config.json` with mode `0600` only when it is absent. Existing configuration remains operator-owned.
The repository learning integration supplies the persisted repository UUID and package scope `github.com/repositories/<repository-uuid>`. The store primitive creates `<root>/repositories/<repository-uuid>` with mode `0700` and writes the package's default `config.json` with mode `0600` only when it is absent. Existing configuration remains operator-owned.

Hub does not create stores or invoke repository learning commands yet.
Decision commands use an existing store and never create one implicitly. The first complete review import prepares the store.

## Command boundary

Expand All @@ -36,7 +36,27 @@ The runner starts Node.js with the configured CLI entry point, appends `--json`,

Hub passes store paths and repository scope as command arguments, not inherited `REPLICA_LEARNING_*` variables. It does not pass database, authentication, workload-identity, storage, or other deployment credentials. Standard output is limited to 16 MiB, standard error to 1 MiB, and the default deadline is 60 seconds. A timeout, output overflow, cancellation, or surviving descendant kills the command's process group before Hub removes the temporary directory.

Later repository mutations use the PostgreSQL advisory-lock primitive for one Hub-wide learning execution at a time. Losing that database connection aborts the operation and its command through the shared signal. This preserves the CLI process boundary without moving package policy into Hub.
Repository decisions, runs, and redactions use the PostgreSQL advisory-lock primitive for one Hub-wide learning execution at a time. Losing that database connection aborts the operation and its command through the shared signal. This preserves the CLI process boundary without moving package policy into Hub.

## Repository API

The browser contracts are:

- `GET /api/repositories/:repositoryId/learnings`
- `POST /api/repositories/:repositoryId/learnings/runs`
- `POST /api/repositories/:repositoryId/learnings/:learningId/decision`

Current product authorization has Hub members and Hub administrators but no repository-specific role model. Signed-in members receive the Learnings contract's access-denied response without suggestion, evidence, permission, Copilot, or usage data. Hub administrators may read accepted guidance and recall previews and may make decisions. Every write rereads the live session and administrator authority immediately before it reaches the package store.

The read response lists the ten newest persisted runs and decimal Copilot usage from runs started during the previous 30 days. It resolves every displayed package event against the current repository snapshot and shows the exact imported event body only when the event, episode, comment, Hub origin, and repository all match. Deleted comments remain visible as redacted evidence without text.

Decision inputs follow the browser schema. Accept and reject require the exact reviewed digest; package `stale_review` failures return `409` rather than applying a changed suggestion. Reject and retire require a reason. Edited acceptance writes the proposed content to a private temporary file because command-line arguments must not carry review text. Successful and failed package decisions write typed security audits without storing content, evidence, or reasons.

The run endpoint requires a usable Copilot connection. It captures and digests one complete repeatable-read repository review snapshot, creates or reuses the repository's active run, writes its typed request audit, and enqueues one idempotent on-demand job. Enqueue failure marks a newly created run failed. A scheduled recovery sweep re-enqueues queued runs.

The worker claims a queued run only once under the learning execution lock. It recaptures the snapshot and refuses drift, prepares the private store, records the initial review and instruction grant when no earlier Hub review grant exists, imports with `--redact-deleted`, labels at most 400 comments and ten Copilot requests, and consolidates at most ten suggestions over the previous 90 days. It records partial label counts and AI-credit usage even when a later request fails. An incomplete collection, changed snapshot, ended consent, refused credential, or unreadable package result becomes a visible failed run.

Soft deletion queues an idempotent package redaction job after the review transaction commits. The recovery sweep also finds deleted review comments, and every later import uses `--redact-deleted`, so a transient queue failure cannot make a deleted body permanently eligible.

## Configuration

Expand All @@ -54,14 +74,6 @@ Later repository mutations use the PostgreSQL advisory-lock primitive for one Hu

The environment-token mode may obtain its secret through a platform secret reference, but the learning child receives only the allowlisted values above. The GitHub App provider supplies a fresh credential for each command without changing that process boundary, so short-lived credentials are never durable connection identity. Organization Copilot model policy, budget controls, and installation revocation continue to apply to every request.

## Remaining integration seam

Repository learning runs can consume `captureRepositoryReviewSnapshot()` from the [review backend](review-collaboration.md#learning-snapshot-seam). A future orchestration layer can:

1. Authorize the repository operation.
2. Derive a stable package scope and prepare its store.
3. Acquire the learning execution lock.
4. Capture the complete repeatable-read review snapshot.
5. Invoke package import, labeling, consolidation, decision, redaction, or recall commands.
## Current limits

That integration must keep the package's consent and lifecycle rules intact. It must not create another Hub review store or omit deleted-message and resolution-history records from the imported snapshot.
The first production flow is explicit: a repository administrator requests a run. Hub does not yet schedule daily discovery runs based on comment changes. Repository-specific roles are also not modeled yet, so current product authorization uses live Hub administrator authority. The package remains authoritative for consent, evidence eligibility, lifecycle, recall, and redaction.
21 changes: 21 additions & 0 deletions hub/schema/learning-decision-operation.prisma
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
model LearningDecisionOperation {
// ID columns
id String @id @default(uuid()) @db.Uuid
repositoryId String @map("repository_id") @db.Uuid
actorMembershipId String @map("actor_membership_id") @db.Uuid

// Relations
repository Repository @relation(fields: [repositoryId], references: [id], onDelete: Cascade)
actorMembership Membership @relation(fields: [actorMembershipId], references: [id], onDelete: Cascade)

// Attribute columns
learningId String @map("learning_id") @db.VarChar(255)
decision String @db.VarChar(20)

// Timestamp columns
createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3)
updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3)

@@index([repositoryId, createdAt])
@@map("learning_decision_operations")
}
6 changes: 6 additions & 0 deletions hub/schema/learning-run-state.enum.prisma
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
enum LearningRunState {
QUEUED
RUNNING
SUCCEEDED
FAILED
}
Loading
Loading