# Repo-backed Knowledge Base

> Canonical path: `specs/kb/repo-backed-knowledge-base.md`
> Status: living product-engineering spec
> Scope: top-down architecture for KB sources backed by AGS repositories.

## 1. Architecture

Knowledge Base is a MeshX control-plane product built on AGS repository primitives.

```text
Web product route
  -> MeshX KB API
  -> MeshX source and permission model
  -> resource_repositories mapping
  -> AGS repository API
```

MeshX owns product truth. AGS owns repository truth. The mapping between product resources and repositories is explicit and durable.

The browser route is a product contract. It can expose `/browse`, `/activity`, `/convergence`, `/knowledge`, or `/labels` while the data layer calls AGS paths such as repository tree, issues, pulls, wiki, and labels.

## 2. Resource Repository Mapping

All repository-backed product resources use `resource_repositories`.

Required concepts:

- `workspace_id`
- `resource_type`
- `resource_id`
- `repo_role`
- `owner_kind`
- `repo_owner`
- `repo_name`
- `repo_full_name`
- AGS repository id
- default ref
- visibility
- user-visible flag

KB source roles:

| Role | Repository | Purpose |
| --- | --- | --- |
| `canonical` | `<storage_owner>/<source_slug>` | User-authored source repository; primary source detail surface in default mode. |
| `mirror` | `<storage_owner>/<source_slug>` | Mirrored source repository; primary source detail surface in mirror mode. Replaces `canonical` for mirrored sources. |
| `insights` | `<storage_owner>/<source_slug>.kb` | System-managed backend repository for generated insights, graph artifacts, and wiki pages. |

A source creates exactly one user-visible repository plus one `insights` repository:

- Default mode (`repo_mode` unset or `canonical`): creates `canonical` + `insights`.
- Mirror mode (`repo_mode=mirror`): creates `mirror` + `insights`. No `canonical` repository is created.

For mirrored sources, an explicitly configured default ref must name an
existing upstream branch and is never silently replaced. When no ref is
configured, mirror sync resolves the upstream symbolic `HEAD`; a repository
with no resolvable `HEAD` may use its only branch, but must not choose an
arbitrary first branch. Empty repositories remain unavailable for browsing.
After a successful sync, MeshX persists the resolved branch on the source,
mirror mapping, and AGS repository so Browse, indexing, and automation share
one default-ref fact.

Mirror synchronization transfers owned heads and tags into AGS as bare Git
data. If go-git rejects a tree entry because worktree-oriented validation does
not accept a name that native Git can store in a bare repository, MeshX must
retry the transfer through the trusted process-local AGS native mirror
capability. The fallback allowlist is limited to single-backslash entries and
control-character tree-entry errors; other invalid-path failures remain
terminal. Native fallback preserves the same target repository identity,
owned refspec set, receive hooks, timeout and cancellation, and sanitized error
boundary as the primary transfer path.

The repository owner follows the Knowledge Base storage scope: personal storage
uses the owning user's AGS namespace, while workspace storage uses the workspace
AGS namespace. The creating user is represented through AGS collaborator grants
and MeshX repository-access ledger rows; repository ownership does not replace
those access intents.
KB-created source repositories are private AGS repositories. Source creation APIs
do not expose a public/private visibility selector; direct repository access is
materialized through KB repository-access intent instead of AGS public
visibility.

The `wiki` role is retired. Generated wiki content lives in the `insights` repository's AGS wiki pages.

`knowledge_base_sources` stores source metadata and product state. It does not store repository identity.

## 3. Provisioning

Repository provisioning for a new Source is create-only. It does not adopt an
arbitrary AGS repository merely because its owner/name matches the requested
repository identity.

Source display names do not reserve repository names. When a request uses a
derived repository stem, provisioning selects an available primary/insights
name pair across MeshX mappings and AGS. It advances in canonical numeric order
when AGS reports an existing repository that is not yet represented in MeshX
mappings. An explicit repository-name
override remains strict and returns a conflict instead of being changed.

For every required repository:

1. Normalize the Knowledge Base storage-owner namespace.
2. Ensure the AGS owner exists.
3. Verify that the selected AGS owner/name is unoccupied, then create the AGS
   repository.
4. Persist or update `resource_repositories`.
5. Grant the initiating user enough AGS repository access for the product surface they just created.

If AGS reports that a selected repository already exists without an
authoritative `resource_repositories` binding for this Source, MeshX treats it
as a name conflict. Auto-named creation advances to the first remaining free
primary/insights stem; an explicit override stays strict and returns the
conflict. Later lifecycle operations reconcile repositories from the persisted
mapping rather than adopting them by name.

The business resource must not become visible as a usable source unless the required repository mapping exists.

Mirror-mode credential lookup is scoped to the source primary repository (`mirror`), because mirror mode does not create a `canonical` repository. Default mode scopes repository-backed credentials to `canonical`.

### Mirror Credentials

Mirror credential refs are backend-only source metadata. Job payloads, progress
records, source config, browser responses, and logs must not contain token
plaintext. Source responses may expose only a sanitized credential summary.

Supported mirror credential refs:

- `automation-secret://...` refs preserve the source-scoped compatibility path
  for one-time pasted tokens. The secret is encrypted with the automation
  credential key and scoped to the source primary repository.
- `personal-access-token://...` refs point to a MeshX-local personal external
  access token. Personal token plaintext is encrypted with the independent
  personal access token credential key, not the automation credential key.
  Token list and source-detail responses are metadata-only.

Personal external access tokens are workspace-scoped and owner-managed. A user
may attach only their own personal token to a mirror source. Scheduled or manual
mirror sync must resolve the ref at runtime and fail before contacting the
upstream Git remote when the token is missing, revoked, expired, not allowed for
`kb_mirror` usage, or when the remote URL is outside the token's normalized
provider base URL. Provider base URL matching uses scheme, host, and path
boundary semantics, so `https://example.com/gitlab` matches
`https://example.com/gitlab/group/repo.git` but not
`https://example.com/gitlab2/group/repo.git`.

The token owner must continue to be authorized for the source: they need current
workspace access and KB `edit`, `manage`, or `owner` permission for the source's
knowledge base. A deployment that runs scheduled personal-token mirror sync must
provide MeshX a current workspace-access verifier or an equivalent offboarding
projection. Personal-token mirror mutations and sync attempts fail closed when
that workspace-access check is unavailable or denies the owner.

## 4. API Boundary

MeshX KB APIs expose product concepts:

- KBs;
- sources;
- source type;
- source status;
- repository-backed source detail;
- retrieval and reads;
- permissions.

AGS APIs expose repository concepts:

- tree and file reads;
- commits, branches, and diffs;
- wiki;
- issues;
- pull requests;
- labels and milestones;
- releases;
- repository settings.

MeshX may delegate to AGS for repository operations, but Web should not need to understand which AGS endpoint implements a product tab.

KB source repository activity projection is role-aware. User-visible source
repositories (`canonical` for default mode, `mirror` for mirror mode) project
repository commits and releases. The system-managed `insights` repository
projects AGS wiki page create, update, and delete activity because generated
knowledge lives there. Projection is cache-first and read-through: product APIs
that expose repository activity return stored activity, refresh only repositories
for sources already visible to the caller, skip repositories refreshed within
roughly three minutes, and do not rely on a background full-repository scan.

## 5. Web Composition

KB source detail and other repository-backed product surfaces should share the same repository detail shell:

- stable header;
- stable tab row;
- full-height content region;
- route base supplied by the product resource;
- optional path adapter between product tab names and repository primitive paths.

Individual source types select tabs from repository capabilities rather than reimplementing repository pages. This keeps Browse, Activity, Convergence, Knowledge, Labels, Milestones, Releases, and Settings visually and behaviorally consistent across KB source and Memory.

Loading states should preserve the right-side shell and swap the content region to a skeleton or placeholder. Switching between sources should not blank the entire detail surface.

## 6. Retrieval And Revision Binding

Retrieval uses MeshX policy, not repository discovery.

Flow:

1. Authenticate the caller.
2. Resolve KB grant, source policy, and requested scope.
3. Load active source rows.
4. Load repository mappings.
5. Resolve eligible source revisions and generated knowledge revisions.
6. Query indexes or AGS content through an authorized pathway.
7. Return results with source and revision attribution.

Generated answers, citations, audit records, and reproducible reads should bind to commits or equivalent immutable revisions. Branch names are acceptable for fresh browsing but not as the only durable citation identity.

Imported Understand Anything Dashboard data follows the same immutable-read
rule with a separate current pointer. MeshX stores
`SourceRevision.UADashboardCommitSHA`; Dashboard readers pin every insights
repository read to that SHA and never infer current from a branch. Publication
creates a tree and commit through canonical AGS Git object APIs without moving
the insights default branch, then makes the MeshX pointer visible with a
source-revision compare-and-swap. See
[`uploaded-ua-dashboard.md`](./uploaded-ua-dashboard.md).

## 7. Storage Boundary

The durable storage split is:

- `knowledge_bases`: KB metadata and product state.
- `knowledge_base_sources`: source metadata, configuration, and status.
- `knowledge_base_grants`: KB product permissions.
- `resource_repositories`: product resource to AGS repository mappings.
- analysis, revision, job, and audit tables: source processing state and provenance.

Do not put repository identity back onto source rows. Do not create Project compatibility tables or Project-backed source references for KB.

## 8. Failure Semantics

Repository-backed creation should fail before exposing an unusable source if required owners or repositories cannot be ensured.

Recoverable failures should preserve enough state for retry:

- AGS owner ensure failure;
- AGS repository ensure failure;
- repository access intent reconciliation failure;
- mapping persistence failure;
- source metadata persistence failure.

Recovery follows persisted identity instead of rerunning create-only provisioning
against an inferred name. When the required `resource_repositories` mapping was
persisted, reconcile or repair the mapped AGS repository. When no authoritative
mapping exists, remove any confirmed orphan created by the failed attempt before
starting a fresh allocation. Manual repair operates on `resource_repositories`
and AGS repository state, not on inferred repository names.