Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
124 commits
Select commit Hold shift + click to select a range
3755d44
Draft metric definitions from query history and search gaps
zlareb1 Nov 16, 2026
ae9c911
Allow an isolated name for mixed-version checks
zlareb1 Nov 16, 2026
f0fb645
Pin query-history setting defaults
zlareb1 Nov 16, 2026
e093301
Query-history settings distinguish cadence from deadlines
zlareb1 Nov 17, 2026
61cb343
Describe definition draft operations and review reads
zlareb1 Nov 17, 2026
c99ffbd
Document retained definition heads during draft recovery
zlareb1 Nov 17, 2026
7236da2
Show complete definition drafts before publication
zlareb1 Nov 17, 2026
dd7a4f6
Keep definition support counts in memory lineage
zlareb1 Nov 17, 2026
ef24e5e
Fence private definition decisions against erasure
zlareb1 Nov 17, 2026
e348e2d
Fence private publication and source registry erasure
zlareb1 Nov 17, 2026
7e6eba8
Expect retained writer fences in namespace erasure traces
zlareb1 Nov 17, 2026
68fecf8
Allocate query-history migration after mirrored erasure
zlareb1 Nov 17, 2026
fb9756a
Require private draft cleanup before older readers serve
zlareb1 Nov 17, 2026
00c36ba
Keep gap input out of stored draft evidence
zlareb1 Nov 17, 2026
2d08a63
Regenerate statement shapes on the composed schema
zlareb1 Nov 17, 2026
f5e02da
Keep definition review tests within their type contracts
zlareb1 Nov 17, 2026
36f9c6a
Complete definition drafting contracts and Library composition
zlareb1 Nov 17, 2026
d3b59a1
Search readable issues and pull requests with loom_search
zlareb1 Nov 16, 2026
7cb5b33
Unified search descriptions include readable issues and pull requests
zlareb1 Nov 17, 2026
3d23183
Refresh persisted tracker links before discovery
zlareb1 Nov 17, 2026
0a6170f
Describe tracker search results and tag scope
zlareb1 Nov 17, 2026
d6ad9a8
Add named-user cost caps and inbox budget warnings
zlareb1 Nov 16, 2026
08eef91
Include the user budget migration in the schema journal inventory
zlareb1 Nov 17, 2026
acda170
User budgets cover synthesis and scoped warning streams
zlareb1 Nov 17, 2026
7bb66ea
Name budget source entry points and invariants
zlareb1 Nov 17, 2026
6efc641
Define user-budget activation and rollback boundaries
zlareb1 Nov 17, 2026
559e8ec
Allocate user budgets after query-history registrations
zlareb1 Nov 17, 2026
db045e6
Reuse the shared writer fence for budget warnings
zlareb1 Nov 17, 2026
ae12076
Number the budget upgrade rule after mirror erasure
zlareb1 Nov 17, 2026
44ff135
Definition review reuses the canonical absence precondition
zlareb1 Nov 17, 2026
9ab19b4
Merge commit '44ff13518d115a7788406720d395bcc185573ffd' into feat/tra…
zlareb1 Nov 17, 2026
8e8801c
Compose budget caps with current parent contracts
zlareb1 Nov 17, 2026
756fefc
Curation rollout names the existing absence precondition
zlareb1 Nov 17, 2026
59c0d88
Source push notifications request bounded document sync
zlareb1 Nov 17, 2026
59c2b8d
Allocate source push migration after query history and budgets
zlareb1 Nov 17, 2026
760a862
Compose push erasure fences with user budget delivery
zlareb1 Nov 17, 2026
fa3276f
Regenerate the composed source push schema and statement corpus
zlareb1 Nov 17, 2026
7a21db9
Document source push entry points and lifecycle invariants
zlareb1 Nov 17, 2026
a16c010
Push setup SDK summaries contain complete sentences
zlareb1 Nov 17, 2026
a7a2a43
Keep push retirement available and restrict callbacks to held orgs
zlareb1 Nov 17, 2026
6636c36
Allocate source push after user cost budgets
zlareb1 Nov 17, 2026
3bdbadf
Keep push erasure traces aligned with authority order
zlareb1 Nov 17, 2026
38a4077
Define the team-owned GitHub feed record and bounded readers
zlareb1 Nov 17, 2026
f957d03
Import GitHub activity into a separately owned tracker record
zlareb1 Nov 17, 2026
9ca5ffb
Tracker feeds preserve publication cursors and repository identity
zlareb1 Nov 17, 2026
f330852
Publish feed changes in cursor order across repositories
zlareb1 Nov 17, 2026
aaa2eca
Fence feed publication reads on supported storage
zlareb1 Nov 17, 2026
823984f
Test feed publication privacy against lagged repository metadata
zlareb1 Nov 17, 2026
ba72ace
Feed publications retain privacy across replica lag
zlareb1 Nov 17, 2026
5118c8b
Feed UUID privacy accepts the contract integer type
zlareb1 Nov 17, 2026
7663ee2
Merge commit '756fefca353052df1486f1439a603bffb62596ca' into feat/tra…
zlareb1 Nov 17, 2026
a6c42fc
Merge commit '7663ee262c64d95dce2a7832103abfe2fa89791c' into feat/use…
zlareb1 Nov 17, 2026
0697b50
Merge commit 'a6c42fcbb80014ea0802f7edd63b6f9d2e3027bc' into feat/kno…
zlareb1 Nov 17, 2026
aef88ec
Merge commit '0697b5020c30642458af0fc2b0c90e7f4602032c' into feat/tra…
zlareb1 Nov 17, 2026
110a4bf
Pin source push table ownership and replacement rows
zlareb1 Nov 17, 2026
8873efa
Merge commit '110a4bf5f7bc3ee512e13f5c1fd31968185f5364' into feat/tra…
zlareb1 Nov 17, 2026
de71cb1
Tracker search composes with current main
zlareb1 Nov 17, 2026
b3a171d
Compose user budgets with merged source protections
zlareb1 Nov 17, 2026
878c618
Compose source push sync with merged user budget parent
zlareb1 Nov 17, 2026
37570bd
Compose GitHub feed with merged push sync parent
zlareb1 Nov 17, 2026
1a31707
Format the unified search argument table
zlareb1 Nov 17, 2026
c0d6224
Compose budgets with formatted search documentation
zlareb1 Nov 17, 2026
831812c
Compose source push with formatted search documentation
zlareb1 Nov 17, 2026
ab94f48
Compose GitHub feed with formatted search documentation
zlareb1 Nov 17, 2026
ba025b9
Keep tracker search regression fixtures on the planned call path
zlareb1 Nov 17, 2026
14b9a4c
Use the configured test target for tracker ASGI requests
zlareb1 Nov 17, 2026
7d7bd46
Compose tracker search with checked document reads
zlareb1 Nov 18, 2026
5297c23
Merge checked document reads and renumber user budgets
zlareb1 Nov 18, 2026
58817b5
Merge current tracker search parent
zlareb1 Nov 18, 2026
1f7643e
Compose source push with checked document access
zlareb1 Nov 18, 2026
68ff1e9
Compose GitHub feed with checked source push parent
zlareb1 Nov 18, 2026
8692fb5
Merge current tracker search into user budgets
zlareb1 Nov 18, 2026
f1950ef
Compose source push with merged tracker search parent
zlareb1 Nov 18, 2026
2c5517d
Compose GitHub feed with merged tracker search lineage
zlareb1 Nov 18, 2026
b416afd
Regenerate schema for user cost budgets
zlareb1 Nov 18, 2026
dcdea3a
Inherit the official user budget schema artifact
zlareb1 Nov 18, 2026
0206639
Record the official source push schema artifact
zlareb1 Nov 18, 2026
df6fedf
Inherit the official source push schema for the feed
zlareb1 Nov 18, 2026
5a0fe75
Align user budget contracts with checked synthesis
zlareb1 Nov 18, 2026
d52a9e9
Compose source push with current budget contracts
zlareb1 Nov 18, 2026
04f3914
Compose GitHub feed with current source push contracts
zlareb1 Nov 18, 2026
c55a26f
Keep receiving-clock deadlines within the writer lease
zlareb1 Nov 18, 2026
158be48
Compose user budgets with marked request accounting
zlareb1 Nov 18, 2026
9c300d4
Compose source push with marked request accounting
zlareb1 Nov 18, 2026
c985f05
Compose GitHub feed with marked request accounting
zlareb1 Nov 18, 2026
17f2040
Regenerate schema and statement catalog for user budgets
zlareb1 Nov 18, 2026
cbad369
Compose source push with published budget schema
zlareb1 Nov 18, 2026
b7b44fd
Compose tracker feed with published source push schema
zlareb1 Nov 18, 2026
37262ee
Register source push provenance and scope contracts
zlareb1 Nov 18, 2026
d0ed6cb
Compose source push contract registrations
zlareb1 Nov 18, 2026
c7e561a
Register the GitHub feed pipeline actor
zlareb1 Nov 18, 2026
1914232
Test marked namespace spend through the shared budget snapshot
zlareb1 Nov 18, 2026
fd8ab9f
Compose the current marked spend contract
zlareb1 Nov 18, 2026
3bda007
Compose the current source push parent
zlareb1 Nov 18, 2026
3b83dc9
Bound leased sends by the received server clock
zlareb1 Nov 18, 2026
9e5ef4c
Withhold exact user spend from budget status and warnings
zlareb1 Nov 18, 2026
62258c1
Compose source push with private budget status
zlareb1 Nov 18, 2026
3edf410
Compose GitHub feed with private budget status
zlareb1 Nov 18, 2026
0b05afd
Compose source push with the merged budget contract
zlareb1 Nov 18, 2026
bb4006f
Compose GitHub feed with the merged budget contract
zlareb1 Nov 18, 2026
3bcd3e6
Test the push notification action in the source menu
zlareb1 Nov 18, 2026
2179e34
Keep push maintenance on its connected client and configured deadlines
zlareb1 Nov 18, 2026
8707b03
Scope push registry keys and callback lookups by namespace
zlareb1 Nov 18, 2026
7c40a4c
Generate the namespace-keyed push registry schema
zlareb1 Nov 18, 2026
79d5b36
Merge namespace-scoped push setup into the tracker feed
zlareb1 Nov 18, 2026
4277fea
Keep push renewal deadlines inside the lease work window
zlareb1 Nov 18, 2026
27b80d3
Merge the push work-window validation into the tracker feed
zlareb1 Nov 18, 2026
6a13f50
Merge deployment session protection and renumber source push
zlareb1 Nov 18, 2026
0bb1a7b
Keep tracker control versions ahead of persisted state
zlareb1 Nov 18, 2026
ead2a1c
Generate the combined mirror and push schema
zlareb1 Nov 18, 2026
cd97a6d
Merge deployment session protection into the tracker feed
zlareb1 Nov 18, 2026
9f761bc
Round-trip callback organizations through query encoding
zlareb1 Nov 18, 2026
ce3eb5c
Merge exact organization callback URLs into the tracker feed
zlareb1 Nov 18, 2026
b40d6b4
Merge published source push changes into the tracker feed
zlareb1 Nov 18, 2026
a8529cb
Gate tracker feed connections through deployment admission
zlareb1 Nov 18, 2026
d4904c8
Translation checks avoid repeated row and interval scans
zlareb1 Nov 18, 2026
ae5e650
Merge deployment privacy changes into the tracker feed
zlareb1 Nov 18, 2026
392ed2e
Merge bounded translation request planning into the tracker feed
zlareb1 Nov 18, 2026
0c30d3c
English fallback checks reuse destination bodies
zlareb1 Nov 18, 2026
962acf8
Merge shared translation link checks into the tracker feed
zlareb1 Nov 18, 2026
28c962d
Coalescer burst regression controls its window clock
zlareb1 Nov 18, 2026
4545a21
Recall Lab reuses settled scores while editing a query
zlareb1 Nov 18, 2026
665ea03
Keep Recall scores stable while editing a query
zlareb1 Nov 18, 2026
36f3691
Keep translation link validation current within each pass
zlareb1 Nov 18, 2026
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
162 changes: 162 additions & 0 deletions docs/architecture/github-feed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
# GitHub tracker feed

The GitHub feed maintains a team's tracker record in the team's ClickHouse database.
Loom's serving processes read that record through the existing
[read-only tracker source](../features/tracker/record-contract.md). The feed does not
put issue bodies, comments or pull requests in Loom's deployment tables.

## Ownership and credentials

An operator runs the feed as a bounded CLI job, scheduled by the team's job runner.
Before reading the registered endpoint or opening the record, the CLI checks its
actual deployment's storage authority and whether its cell holds the feed organization.
The external connection repeats that deployment gate; it never treats the record's
metadata as deployment authority. The job closes both clients and the deployment's
Postgres pool on exit.
Initialization creates feed tables and contract views in an empty, dedicated database;
it refuses existing objects. The operator then registers that database as a tracker
source with a separate read-only credential. Configuration and sync require that
registered endpoint and its repository allowlist. A separately supplied writer
credential can write only the team's feed database; the reader credential is never
upgraded or reused for writes.

The source credential is a read-only fine-grained GitHub token or App installation
token restricted to the configured repositories: Metadata, Issues and Pull requests,
all read-only. Token permissions are operator-attested configuration: a successful
GET, token prefix or endpoint-permission header cannot certify absence of write grants.
An unidentified host token is not eligible for a read-only live probe. The token is
sealed with the existing secret-root mechanism in the team's
feed configuration table. No token appears in arguments, output or contract views.
The CLI receives the database writer password through a named environment variable;
it does not persist that password. GitHub requests use GET on the fixed
`https://api.github.com` origin, refuse redirects and construct paths from validated
repository names and numeric item ids. They never follow response URLs.

The team owns the copied record, its backup retention and erasure. To erase copied
content, the team stops its scheduled writer and removes the affected feed rows,
comments and checkpoints before restarting with an exclusion or removing the source
repository. Deleting a Loom namespace retires Loom's derived data and grants; it
does not delete the team's record. This is the same boundary as any registered tracker
database. The record-writer credential cannot address Loom's own database; copied
content is never written there. Only the existing deployment-store lease is local.

## Record and progress

Raw items and comments are versioned in the team's database with the identity tuple,
process actor and imported source class. Contract views expose the latest item version,
contract UUIDs and effective visibility. Issue and pull-request comments are
kept separately and included in the corresponding item's searchable body. Unsupported
triage fields use the contract's typed defaults; edges are empty until evidence exists.
Contract `updated_at` is the latest persisted publication timestamp across the item
and its comments, so late imports and comment edits advance incremental tracker reads.
Publication versions use whole milliseconds to match tracker cursors. Under the record's
writer lease, each content batch receives the later of the record clock and one millisecond
beyond every persisted content version for its organization, across all repositories.
This ordering also covers namespaces that read multiple repositories through one cursor.
Repository control writes likewise advance beyond the persisted version for their exact
organization and repository, even when the receiving clock moves backward. Visibility
revocation, credential rotation and cursor checkpoints therefore replace the prior control
row rather than losing to its timestamp.
Raw upstream timestamps remain separate and drive API cursors. No model or embedding
call is required. Repository identities retain the registered allowlist's spelling,
including when the API returns different capitalization.

Owner, repository revision and publication watermark reads request
`select_sequential_consistency = 1`; the writer lease alone does not make a replica
current. Feed writers require SharedMergeTree storage or a single self-hosted server,
following the [read-your-writes guarantees](clickhouse.md#read-your-writes).
The setting alone does not cover acknowledged writes on self-hosted replicated tables.
Writer validation accepts only `ReplacingMergeTree` and `SharedReplacingMergeTree`
for the five feed tables in the connected record database. Replicated, distributed
and unrecognized table engines are refused before the job can publish.

Each repository has independent item, issue-comment and review-comment cursors. The
[issues endpoint](https://docs.github.com/en/rest/issues/issues#list-repository-issues)
lists issues and pull requests together; pull requests are hydrated through their
numeric endpoint. The
[issue comments endpoint](https://docs.github.com/en/rest/issues/comments#list-issue-comments-for-a-repository)
and [review comments endpoint](https://docs.github.com/en/rest/pulls/comments#list-review-comments-in-a-repository)
have separate updated-time scans. Each uses ascending `updated_at`, bounded pages,
response bytes and request time. Cursor advancement follows acknowledged writes only,
through a complete timestamp boundary. Requests lower the saved timestamp by one second
because `since` is exclusive. A full page budget saves the earliest timestamp on its
final page; the next turn replays that boundary. The budget is 2 to 100 pages: a preceding
page permits progress while the final page retains an incomplete timestamp boundary.
If one timestamp fills the entire configured page budget,
the job reports a capacity error and keeps the checkpoint rather than skipping rows or
claiming progress. The operator can raise the bounded page budget for that repository.
Replayed rows replace the same identity. The API is a changing collection, not a snapshot;
overlapping scans reduce pagination races without claiming transactional upstream reads.

Every turn verifies repository identity and visibility before copying content. An
unavailable, moved or mismatched repository first hides that repository's contract rows
and then refuses the turn. Contract views also require a recent successful visibility
observation, expiring after a bounded interval if the scheduler stops. Each item and
comment publication stores the observation's privacy classification in the same row as
its content. Views use the most restrictive classification from the repository, item
and stored comments for both `is_private` and the contract UUID. A replica that learns
new content before repository metadata therefore cannot label a private publication
public. The standard tracker's existing predicate excludes those rows. Restricted
namespaces retain their live direct-grant check. Visibility is a polling observation,
not an instant permission mirror.
A validated identity mismatch or private observation can hide the current record even
when another turn changed its revision; this preserves current credentials and cursors.
Generic failures from an older credential retain the revision check. Stale public
observations cannot widen access.

When a repository becomes public, configuration or sync resets its existing stream
cursors before publishing public metadata. Bounded scans replay the items and comments
and stamp each with the public observation. An item remains restricted until its own
row and its stored comments have been replayed. Repeated scheduled turns continue a
backlog under the same page and timestamp-boundary limits. Deleted upstream rows cannot
be replayed; the team must erase those retained copies to clear their private
classification.

Incremental API lists do not report deleted issues or comments. The team handles those
erasures explicitly; the feed does not claim deletion detection. Configuration, sealed
credentials and cursors stay with the team's record, so CLI restarts do not depend on
local files. Initialization binds the record to one Loom deployment's database UUID;
configuration and sync refuse any other deployment. Concurrent jobs in that deployment
use one publication lease keyed by the record database UUID, independent of source
aliases and repository renames. Provider fetches happen outside that lease; initialization,
configuration and publication share it so concurrent first-time identity observations
cannot bypass serialization. An uncertain database write retains its claim through the bounded
server send window. Record erasure requires the team to stop all writers first.

## Validation and rollout

Fakes cover pagination ties, partial responses, rate limits, retries, visibility changes,
redirects and credential redaction. A private ClickHouse verifies the contract, current
views, replay and interrupted cursor publication. A read-only token, when available,
checks a bounded public-repository slice; a write-capable CLI token is never substituted.
The feed adds no Loom wire operation or automatic worker. Existing deployments and
registered trackers are unchanged until an operator initializes and schedules a feed.

## Source entry points

- [CLI](../../server/cli/tracker_feed.py): `register_tracker_feed` and `_run` select the
owned record and its separate writer credential; `_validate_writer` checks grants
and supported table engines.
- [Feed application](../../server/tracker/app/github_feed.py): `initialize`, `configure`,
`sync` and `_publish` enforce ownership, stamp publication privacy and fence writes.
- [Record store](../../server/tracker/store/github_feed.py): `statements` defines the
contract views; `repository`, `put_repository` and `put_items` read publication
state consistently.
- [API client](../../server/clients/github_feed.py): `pages` bounds upstream scans;
[domain rules](../../server/tracker/domain/github_feed.py) validate identities and
choose replay boundaries through `next_cursor`.

## Invariants

- Copied content stays in the team's registered record, with team-owned erasure.
- Repository identity, visibility and revision checks precede content publication;
control reads include acknowledged record writes on the supported storage topology.
- Content and its privacy classification share one raw row version. Contract privacy
and UUIDs include every stored component's classification, even when tables lag
independently.
- A private-to-public transition resets cursors before public publication, so retries
replay retained content without dropping its private classification prematurely.
- The record-wide writer lease covers publication and checkpoint writes. An uncertain
send retains its claim until it settles; a cursor advances only after acknowledged writes.
- Whole-millisecond content versions increase across every repository in the record,
so combined item/comment bodies remain visible to existing tracker cursors.
118 changes: 118 additions & 0 deletions docs/features/tracker/github-feed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Maintain a GitHub tracker record

`loom tracker-feed` copies repository issues, pull requests, issue comments and inline
review comments into a team's dedicated ClickHouse database. Loom reads the resulting
views through a [read-only tracker source](record-contract.md). The team owns the copied
content, backups and erasure. The job makes no model or embedding calls.

## Prepare the record

Use an empty database with a stable database UUID, separate from the Loom deployment
database. Give a dedicated writer permission to create tables and views and to read and
insert rows in that database. Keep its credentials separate from the tracker reader.

```sql
CREATE DATABASE team_feed;
CREATE USER feed_writer IDENTIFIED BY '…';
GRANT CREATE TABLE, CREATE VIEW, SELECT, INSERT ON team_feed.* TO feed_writer;
GRANT SELECT ON system.columns TO feed_writer;
GRANT SELECT ON system.databases TO feed_writer;
GRANT SELECT ON system.tables TO feed_writer;
CREATE USER feed_reader IDENTIFIED BY '…' SETTINGS readonly = 2;
GRANT SELECT ON system.columns TO feed_reader;
```

Supply the writer password as `LOOM_TRACKER_FEED_WRITER_PASSWORD` through the scheduler's
secret facility. Run the CLI with the same Loom deployment configuration used by the
serving process, including its ClickHouse connection and secret root.
Set `LOOM_TRACKER_ORG` to the organization being initialized. The CLI verifies direct
writer grants before use and refuses roles, grant options and authority outside this
database, apart from those three system metadata tables.

```bash
loom tracker-feed init --org acme --host record.example --database team_feed \
--writer-user feed_writer
```

Initialization creates `github_issues`, `github_prs` and `edges` as definer views.
Grant the reader access only to those views:

```sql
GRANT SELECT ON team_feed.github_issues TO feed_reader;
GRANT SELECT ON team_feed.github_prs TO feed_reader;
GRANT SELECT ON team_feed.edges TO feed_reader;
```

[Register the tracker source](record-contract.md#adding-a-tracker-source) in views mode
using `feed_reader`. Include each repository in the source's namespace allowlist and
use restricted namespaces for private records. Set the deployment's `LOOM_TRACKER_ORG`
to the same organization. Source registration keeps its existing host, credential and
contract checks. HTTP and private addresses require the development private-host
setting; production connections use HTTPS.

## Configure and schedule a repository

Create a read-only fine-grained token or App installation token restricted to the
repositories being copied. It needs Metadata, Issues and Pull requests read permissions.
`--read-only-token` is the operator's permission attestation; the CLI cannot certify the
absence of write grants from a successful request or token prefix.

Supply that token as `LOOM_TRACKER_FEED_GITHUB_TOKEN` through the secret facility, then
configure one allowlisted repository:

```bash
loom tracker-feed configure --org acme --source widgets --repo acme/widgets \
--writer-user feed_writer --read-only-token --max-pages 5
loom tracker-feed sync --org acme --source widgets --repo acme/widgets \
--writer-user feed_writer
```

Configuration seals the token in the team's feed database. Sync needs the writer
password and deployment secret root; it does not need the token environment variable.
Copied repository identities keep the spelling in the registered source's allowlist,
so namespace filters match even if API capitalization differs.
App installation tokens [expire after one hour](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).
An external secret process must refresh the installation token and rerun `configure`
before expiry. The feed does not issue or refresh installation tokens.
Use `--writer-password-env` or `--token-env` to select another credential variable.
During a root-secret rotation, successful metadata writes reseal credentials opened by
`LOOM_JWT_SECRET_PREVIOUS`. Complete a successful turn before retiring the previous root.

Schedule `sync` every five minutes or more frequently. Visibility observations expire
after 15 minutes, hiding the repository if checks stop succeeding. Each job has a
120-second limit and reads at most `--max-pages` pages per stream, with 100 items per
page and a budget of 2 to 100 pages. The final page's timestamp boundary is replayed;
the minimum leaves a preceding page from which to make progress.
A capacity error leaves the cursor unchanged; raise
the bounded page budget or shorten the repository's backlog before retrying. Counts
on standard output report processed rows, including replayed rows.

## Visibility and erasure

Every stream verifies the repository's immutable identity and current visibility.
Failed checks hide its views. Each item and comment keeps the observation's privacy
classification with its content. The views use the most restrictive classification
from the repository, item and stored comments, including when those tables reach a
replica at different times. This is a polling observation with a bounded expiry,
rather than an instant permission mirror. Normal tracker privacy and direct grant
checks still apply.

When a repository becomes public, configuration or sync resets its cursors and
scheduled turns replay all streams within the same page budget. An item becomes public
after its row and stored comments have been refreshed under public observations.
Deleted upstream rows require erasure of the retained copies; replay cannot refresh them.

Bodies include up to 32,768 item characters and the 64 most recently updated comments,
with up to 2,048 characters per comment. Review requests and test evidence remain
unknown when the source does not provide that evidence.
The views' `updated_at` tracks item and comment publication in the record, so a comment
imported after its item remains visible to incremental tracker reads.

Incremental lists do not report deletions. To erase copied content, stop every scheduled
writer, erase the affected raw rows, comments and repository configuration or cursors,
and exclude the repository before restarting. Dropping a Loom namespace removes Loom's
derived data; it does not erase the team's database or backups. Initialization binds a
record to one deployment and organization. Use a separate record for another deployment.

See the [feed architecture](../../architecture/github-feed.md) for cursor boundaries,
concurrency and ownership.
1 change: 1 addition & 0 deletions docs/features/tracker/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,7 @@ Thresholds, legs, judge, rerank, bisect scope and test-signal settings are in th

## Related

- [GitHub feed](github-feed.md): maintain a team-owned record with a scheduled CLI job
- [Record contract](record-contract.md): tables, columns, aliases, mapping mode, sources
- [History and PRs](../code-index/history-and-prs.md): the code-plane ops that read a tracker
- [Adding repositories](../code-index/repositories.md)
Expand Down
Loading
Loading