# Version 1 classification rules

[`PRODUCT.md`](PRODUCT.md) incorporates this document as normative version 1 behavior.

## Version-control systems

Version 1 supports Git work trees only.
Git classification uses repository discovery, index state, nested `.gitignore`, `.git/info/exclude`,
the configured global excludes file, submodule boundaries, linked worktree administration, and
repository-common administration data.
Authoritative queries use direct `git` argument vectors only when stable files cannot provide the
same semantics safely.

A workspace without established Git semantics remains source-bearing.
Other VCS markers make affected content manual-only with an unsupported-VCS warning.
No unsupported VCS command is invoked.

## Source and document classes

Outside an established repository, a regular file is heuristic source when its basename is one of
these generated values:

<!-- generated: source-basenames -->
- `Makefile`
- `CMakeLists.txt`
- `build.zig`
- `build.gradle`
- `pom.xml`
- `package.json`
- `Cargo.toml`
- `go.mod`
- `Gemfile`
- `composer.json`
<!-- end-generated: source-basenames -->

or its lowercase suffix is one of:

<!-- generated: source-suffixes -->
- `.c`
- `.cc`
- `.cpp`
- `.cxx`
- `.h`
- `.hh`
- `.hpp`
- `.java`
- `.kt`
- `.kts`
- `.scala`
- `.groovy`
- `.gradle`
- `.zig`
- `.zon`
- `.rs`
- `.go`
- `.lua`
- `.nu`
- `.py`
- `.pyi`
- `.rb`
- `.php`
- `.js`
- `.jsx`
- `.ts`
- `.tsx`
- `.vue`
- `.svelte`
- `.sh`
- `.bash`
- `.zsh`
- `.fish`
- `.sql`
- `.proto`
- `.toml`
- `.yaml`
- `.yml`
- `.json`
- `.xml`
- `.html`
- `.css`
- `.scss`
- `.md`
- `.rst`
<!-- end-generated: source-suffixes -->

This heuristic can only make a finding manual-only.
Unknown suffixes never prove that a file is not source.

Default document roots are existing directories named by the generated catalog below directly below
`$HOME`, plus configured document roots.

<!-- generated: document-roots -->
- `Documents`
- `documents`
- `Download`
- `Downloads`
<!-- end-generated: document-roots -->
Downloads retain their separate policy from `PRODUCT.md` section 5.3.
A missing default root is silently absent; an inaccessible configured root produces a warning.

## Ownership states and namespaces

Ownership is one of:

- `authoritative`: one owner proves the exact namespace and item;
- `unknown`: no authoritative owner was established;
- `incomplete`: an ownership source failed or exceeded a bound;
- `conflicting`: authoritative sources claim overlapping ownership;
- `unavailable`: the owner is known but its required adapter capability cannot be used.

Only `authoritative` ownership can enable package execution or direct mutation inside a controlled
namespace. Every other state remains reviewable and makes mutation unavailable.

Controlled namespaces include manager installation roots, stores, caches, configuration roots,
service roots, runtime roots, and tool-managed environments declared by a shipped adapter.
Containment by path is supporting evidence only; the adapter must establish the namespace root and
native identity.

## Evidence vocabulary

Classification provenance is:

- `manager_metadata`
- `manager_query`
- `documented_format`
- `vcs_metadata`
- `operator_configuration`
- `process_observation`
- `filesystem_metadata`
- `path_heuristic`
- `name_heuristic`

Confidence is `authoritative`, `documented`, `observed`, `heuristic`, `unknown`, or `contradicted`.
Contradicted evidence overrides positive evidence and disables execution.

Producer-specific disposal evidence is exactly one of:

- an authoritative manager effect set naming the item or immutable scope;
- documented producer metadata marking the exact artifact disposable;
- a documented cache format proving the exact entry redundant;
- validated FreeDesktop trash metadata proving deletion time and trash ownership;
- operator configuration making an item manual-only, never recommended.

Recommendation requires one of the first four evidence kinds, authoritative ownership where a
controlled namespace applies, complete bounded authority data, and no contradiction.
Age, pathname, suffix, target absence, negative process observation, apparent size, and generic
location are supporting evidence only and never satisfy recommendation alone or in combination.
When no producer evidence establishes purpose, classification is `uncertain purpose`, manual-only,
and unavailable for bulk selection.

## Downloads

Version 1 recognizes an installer or archive only when both a case-insensitive suffix and file magic
agree for ZIP, gzip, bzip2, xz, Zstandard, tar, Debian package, RPM, APK, Android APK, or Java archive
formats. A mismatch is `uncertain purpose`.
Duplicate names, numbered suffixes, and content hashes do not prove that one copy is disposable.
All download findings are manual-only unless an authoritative adapter proves an exact redundant
cache entry.

## Trash

Version 1 validates FreeDesktop Trash Specification version 1.0 layouts and adapter-documented trash
formats. A FreeDesktop item requires one matching `.trashinfo` file, valid UTF-8 keys, exactly one
`Path` and `DeletionDate`, percent-decoding without NUL, a normalized path within the applicable
trash namespace, and a representable timestamp.

Unknown keys are ignored only for FreeDesktop forward compatibility.
Duplicate required keys, malformed escapes, missing pairs, conflicting entries, future format
versions, namespace escape, or invalid timestamps make the item manual-only with unknown deletion
age. Such metadata never enables recommendation.

## Logs, locks, and temporary files

Lock files are recognized before logs by exact producer metadata or the suffixes `.lock`, `.lck`,
and `.pid`; they are never classified as logs from a shared name fragment.
Log recognition requires a documented producer path or the suffix `.log`.
Rotated logs require a log identity plus `.N`, `.old`, `.gz`, `.bz2`, `.xz`, or `.zst` rotation.
Compression suffix alone is not log evidence.

Known temporary locations are `$TMPDIR`, `$PREFIX/tmp`, and adapter-declared producer temporary
roots. Name heuristics are a leading or trailing `~`, `.tmp`, `.temp`, `.swp`, `.swo`, or `.part`.
Location and name heuristics permit manual review only.
Producer-specific evidence remains required for recommendation.

## Process observations

A file is `open` when one bounded `/proc/<pid>/fd` snapshot resolves a descriptor to the same trusted
device and inode. It is `mapped` when one bounded `/proc/<pid>/maps` snapshot identifies the same
trusted device and inode. Permission or capacity failure makes process evidence incomplete, never
negative.

`Actively changing` requires two metadata samples separated by at least one second on a monotonic
timer, with a changed size, modification timestamp, or identity. The worker performs other admitted
work or waits on the normal timer facility; tests use an injected clock and never sleep.
A file that is open, mapped, or actively changing is manual-only.
No observed reference means only `no reference observed`; it never proves inactivity.