---
title: What the database stores
description: Understand tzTrack's issues, reports, comments, history, and related records, with plain-language explanations of their fields and who updates them.
slug: /reference/what-the-database-stores
order: 7
visibility: public
redirects_from: []
---

# What the database stores

A tzTrack space holds issues and the records that explain them: reports, comments, history, and related work. This page explains what those records contain; you can ask your AI about them without knowing the API or the database's internal layout.

## How the records fit together

An **issue** tracks one point. **Reports** preserve observations of that point, **comments** record the work and discussion, and **history** records changes automatically. The issue holds the current status and, eventually, the resolution.

Several reports can support one issue. A report can also link to several issues if it contains separate points. Relationships connect issues—for example, when one duplicates another or follows from it. These are records and connections you can ask about, not tables you need to maintain yourself.

## Issues

Your AI updates the issue as work progresses. Some fields are optional or filled only when they become useful.

| Field | What it tells you |
| --- | --- |
| Number and title | Which issue this is and the point it tracks. |
| Kind | Whether it is a bug, gap, question, task, idea, or another supported kind. |
| State and outcome | The work's current status and, when closed, how it ended. |
| Summary | An optional explanation of the current understanding. Most issues currently have no summary; read the title, reports, and comments for the detail. |
| Area, labels, and requirements | Which part of the project is affected, how the issue is grouped, and any requirements it concerns. |
| Priority | Assigned urgency: 1 urgent, 2 soon, or 3 when convenient. It can be unset, and ideas have no priority. |
| Effective priority | Urgency after an applicable automatic boost from qualifying reports. A person-set priority is not automatically boosted. |
| Ranking score | A calculated score based on reports, impact, and recency, used to help order work. It is not another urgency scale. |
| Impact assessment | How much the problem affects people, how widely it may occur, and the reason for the assessment. |
| Alarm | A marker for a serious concern, such as security, data loss, or billing. |
| Workaround | A way to avoid or reduce the problem before it is resolved. |
| Claim and stale-claim flag | Who is working on it, and whether that claim has gone untouched for a day. A stale claim does not release itself. |
| Waiting for | The person, reply, outside event, or evidence needed next. |
| Due date and plan | A task's deadline and any recorded plan for the work. |
| Resolution | What was done or decided, why nothing changes, or what evidence would settle an issue waiting for evidence. |
| Fixed in | The release and environment serving a fix, when recorded. More detailed fix records can also be attached. |
| Note to reporters | A short update or instruction intended for everyone who reported the problem. |
| Restricted access | Whether the issue is withheld from people with lower access. |
| Counts and dates | How many reports and distinct reporters support it, when it was last reported, and when it was created, changed, or closed. |

The summary, a comment, and the resolution serve different purposes. The summary describes the current understanding; a comment records a particular update; the resolution explains the result.

## Reports

A report is a finding as it was filed. It supplies evidence for an issue rather than replacing the issue's current fields.

| Field | What it tells you |
| --- | --- |
| Reporter and filing time | Who or which AI submitted the finding, and when. |
| Title and description | What was observed. |
| Kind and origin | What sort of finding it is and where it came from, such as project work or a user report. |
| Impact | Whether the reporter was blocked, needed a workaround, was inconvenienced, or reported no impact. |
| Evidence and its basis | Supporting details and how they were obtained. A reporter's claim is distinct from evidence confirmed by a check. |
| Seen in | The release and environment where the problem occurred, when known. |
| Proposed resolution and workaround | The filer's suggested fix or way to keep working. |
| Attachments | Images supplied with the report. |
| Recurring-problem identifier | A stable identifier that helps repeated findings join the same issue. |
| Amendment or withdrawal | Whether this report corrects or withdraws an earlier filing. |

Reports preserve the original filing rather than being rewritten as the issue changes. A correction is recorded as an amendment. Retention, deletion, and privacy rules can remove report content.

## Comments and history

| Record | Fields and purpose |
| --- | --- |
| Comment | Its number, author, date, text, and any attachments. Your AI adds comments for findings during investigation, progress, discussion, or a handoff. A comment does not increase the report count. |
| History entry | The action, who performed it, when it happened, and the changes or details recorded for that action. The service adds history as actions occur; your AI does not need to write a separate history entry. |

For example, “I reproduced this in Firefox” can be an investigation comment. A separate user's original report of the same failure is another report. “Priority changed from 3 to 2” is a history entry.

## Watches

A watch sends one messaging handle a message each time an issue's state, outcome, or `waiting_for` changes. Each watch holds its handle, who set it and at which permission level, whether it ends when the issue closes, and when it lapses: 30 days after it was last set.

A watch is kept beside the issue, not in it. It adds no history entry and does not change when the issue was last changed. The messages a watch sends after a change are kept, with their handle and text, for seven days. A `read` gives the number of standing watches as `watchers`, and [Watching an issue](/tztrack/reference/the-tools/#watching-an-issue) explains the messages.

## Links, relationships, and review proposals

| Record | What it holds |
| --- | --- |
| Report link | Which report supports which issue, when it was linked, and the basis for the link. |
| Issue relationship | How one issue connects to another, such as a duplicate, related topic, or follow-up. |
| Review proposal | A suggested change from background AI review, such as combining duplicate issues or separating distinct points, awaiting its required review or action. |
| Attachment | An image's identity, size, and media type, associated with its report or comment. |

Combining duplicate issues retains the evidence through the linked reports. It is different from simply closing work as completed.

## Fixes, releases, and checks

These records are useful for coding projects and automated monitoring. A writing or research project may never need them.

| Record | What it holds |
| --- | --- |
| Fix record | The issue, the code change that addresses it, its tests or other proof, who recorded it, and where it has shipped. |
| Release record | The release line, version, code change, environment, and when the release became live or was withdrawn. A release line identifies a series of releases, such as one app or service. |
| Check record | What was checked, its covered areas, who ran it, counts of runs and passes, first and latest failures, latest success, and the issue associated with a failing check. |

Recording a fix, releasing it, and verifying it are distinct events. These records help your AI explain which stage has been reached.

## Space, access, and automation settings

| Setting | What it controls |
| --- | --- |
| Space identity and name | Which project's issue database a session uses. |
| Owner and members | Who owns the space and who can access it. |
| Access level | Whether a member can report and read, contribute work, or also close and reopen issues. Sharing stays with the account that owns the space. |
| Default space | For each account, the space its calls use when they name none, the space it replaced, and when it changed. It is kept for the account, not inside any space, and is removed when the account is deleted or the last space it can reach is deleted. |
| Areas and release lines | How the project's issues and software releases are grouped. |
| Background AI reviews | Whether tzTrack runs its optional triage and independent reviews. These are separate from your connected AI tool. |
| Review limits | Bounds on automated review work, including its model-call allowance and review safeguards. |
| Priority and ranking settings | How qualifying reports contribute to automatic priority boosts and ranking. |

[Issues and kinds](/tztrack/concepts/issues-and-kinds/#background-ai-reviews) explains when background reviews help and their plan availability. [Sharing a space](/tztrack/concepts/sharing-a-space/) explains access.

## For AI tools: current field names

Use the current public names in requests and when interpreting responses. The API's names do not describe the service's internal storage layout.

| Readable label | Current field name |
| --- | --- |
| Report's reporter | `reporter` |
| Comment's author and number | `author`, `number` |
| Who performed a recorded action | `performed_by` |
| Impact assessment and assessor | `impact_assessment`, `assessed_by` |
| Note to reporters and its source | `note_to_reporters`, `note_source` |
| Basis for a report seen after a fix | `seen_after_fix_basis` |
| Release line or lines | `release_line`, `release_lines` |
| Basis for a report link | `link_basis` |
| Image size and media type | `size_bytes`, `media_type` |
| Claim lease's last renewal | `last_renewed_at` |
| Due date | `due_date` |
| Effective priority, ranking score, stale-claim flag | `effective_priority`, `ranking_score`, `claim_stale` |
| Automation and review settings | `automation`, `ai_reviews_enabled`, `upstream_sharing` |
| Critical actions | `critical_actions` |
| Review call allowance and merge safeguard | `model_calls_per_day`, `merge_error_rate_threshold` |
| Priority boost settings | `priority_boost_report_threshold`, `priority_boost_window_days`, `max_counted_reports_per_account` |
| Internal-report ranking weight | `internal_report_ranking_weight` |
| Check thresholds | `check_issue_thresholds`, `consecutive_failures`, `result_change_count` |
| Check run and pass counts | `run_count`, `pass_count` |
| Check failure and success records | `first_failure`, `last_failure`, `last_success` |

Use `level` for access permissions, `actor` for a request's actor, and `type` for a relationship's type. Assigned `priority` is distinct from derived `effective_priority`. Read each field in the context of its record or request.

[The tools](/tztrack/reference/the-tools/) defines MCP inputs. [REST API](/tztrack/reference/rest-api/) covers scripts and configuration. The [Issue Tracking contract](https://turnzero.ai/cloud/backend-packages/tztrack/) gives the complete field shapes, bounds, and permissions; this page explains their meaning rather than duplicating that schema.

## Related

- [Glossary](/tztrack/concepts/glossary/): short definitions.
- [Issues and kinds](/tztrack/concepts/issues-and-kinds/): the workflow and optional background reviews.
- [Waiting and claims](/tztrack/concepts/waiting-and-claims/): dependencies and responsibility.
- [What happens without asking](/tztrack/concepts/what-happens-without-asking/): what the MCP instructions ask your AI to do.