cancho-toolstally 0.1.0
Count distinct lines or fields and report the most frequent, ordered by count then bytewise key; one bounded pass, the same answer on every machine.
tally [--root DIR] [--field N [--delim D]] [--top N] [--max-keys N] [--max-line-bytes N] [--format json|text] [FILE...]- output
- one JSON document
- schema
- tally.v1
- reversibility
reversible-cheap- guarantees
deterministic,idempotent,bounded_memory- concurrency
- read-only: it never writes, so any number may run at once
- confinement
beneath: with --root, paths are checked lexically against it and then opened beneath it one component at a time, following no symbolic link (path.symlink), so nothing outside the root is reachable through one; without it, a reader opens the path as given, links and all, and a writer still follows no link in the file's own name- reads the environment
- no
- reads the clock
- no
- compiler
- de4e52fd8180
- for an agent
- SKILL.md (
tally skill)
Authority
Derived by cancho authority from the source, embedded in the binary, and checked against tools.toml's ceiling in CI. Every label is bounded.
- args
- dir_read
- err_write
- file_read
- fs_read("")
- heap
- io_read
- io_write
What the row cannot say:
- path extent: a path from the command line is checked at run time, so the row says fs_read("")
- what a symlink reaches
- what standard output carries
- resource use beyond the tool's own caps (memory, wall time)
- per-invocation behaviour such as --dry-run, which the row cannot see
Operands
| Operand | Role | How many | Meaning |
|---|---|---|---|
FILE... | path-read | 0 or more | the files to count, in order, none reads standard input |
Flags
| Flag | Kind | Role | Default | Meaning |
|---|---|---|---|---|
--root | path | root | resolve every FILE relative to this directory and refuse paths outside it | |
--field -f | nat | none | count field N (1-based) of each line instead of the whole line | |
--delim -d | text | none | | the one byte that separates fields (default tab) |
--top | nat | none | 10 | how many of the most frequent keys to report (ceiling 1000000) |
--max-keys | nat | none | 100000 | the most distinct keys held, one more is limit.too-many-keys (ceiling 1000000) |
--max-line-bytes | nat | none | 1048576 | the longest line counted, a longer one is limit.line-too-long (ceiling 16777216) |
--format | choice:json/text | none | json | json for a program, text (count, tab, key) for a person |
Limits
| Limit | Default | Ceiling |
|---|---|---|
top | 10 | 1,000,000 |
max-keys | 100,000 | 1,000,000 |
max-line-bytes | 1,048,576 | 16,777,216 |
Exit codes
| Code | Name | Meaning |
|---|---|---|
| 0 | SUCCESS | what was asked was done; zero matches is success |
| 1 | GENERAL_ERROR | the operating system failed mid-operation, or the tool caught a bug in itself |
| 2 | INVALID_ARGS | the invocation is malformed or names something of the wrong kind; nothing was read |
| 3 | NOT_FOUND | a named input does not exist |
| 4 | PERMISSION_DENIED | the operating system refused, or the tool's own confinement did |
| 8 | PRECONDITION_FAILED | the answer is no, or a limit was reached |
Rules (17)
Match on rule, not on the message. A retry repair is an argv that can be run as it stands, and never widens what the tool may touch.
| Rule | Exit | Repair | When |
|---|---|---|---|
args.unknown-flag | 2 | sometimes | a flag that is not in the tool's table |
args.missing-value | 2 | never | a flag that takes a value was given none |
args.bad-value | 2 | never | a flag's value is not of the flag's kind |
args.duplicate-flag | 2 | never | the same flag was given twice |
path.empty | 2 | never | an empty path |
path.dotdot | 2 | sometimes | a path with a `..` component |
path.absolute | 2 | always | an absolute path where one relative to --root is wanted |
path.outside-root | 4 | never | an absolute path that is not under --root |
path.too-long | 2 | never | a path longer than 4096 bytes |
path.symlink | 4 | never | a path that runs through a symbolic link, which the tool does not follow |
io.not-found | 3 | never | a named input does not exist |
io.not-a-directory | 3 | never | a path runs through something that is not a directory |
io.is-a-directory | 2 | never | a directory where a file is wanted |
io.permission-denied | 4 | never | the operating system refused access |
io.read-failed | 1 | never | the operating system failed a read |
limit.line-too-long | 8 | sometimes | a line longer than --max-line-bytes |
limit.too-many-keys | 8 | never | more distinct keys than --max-keys |
Evidence
each gate is a test in cancho-tools/tests/conformance, run by CI on the commit this binary was built from:
- M1 schema conformance
- M2 determinism
- M3 rule coverage and hint soundness
- M4 fault injection
- M5 differential against GNU
- M6 authority
- M7 mutation behaviour
- M8 confinement
- M9 memory flatness
Agent in the loop: not run: no claim that this tool is more agent-friendly than the incumbents is made (cancho docs/agent-toolbox.md section 7.2).