Time Assurance Code Scanner

Open-source, AI-assisted code scanner (tacs) that supports long-horizon time assurance by identifying potential Y2038 / Y2106-class risks in source code around 32-bit time_t and related ABI assumptions.

“Assurance” here means systematically identifying and documenting potential time-related risks and evidence for review. TACS contributes to that process; it does not guarantee that all such risks have been found, and it cannot prove a system free of rollover defects.

This repository is the open-source scanner engine and CLI. It is the code-scanning sibling of time_assurance_doc_scanner (tads).

New here? Follow QUICK_START.md — install through a first local scan (no LLM required).

Status

v0.2.0 — stable CLI-first scanning pipeline. Public result documents use schema_version 1.2 (candidates[], assessments[], findings[], plus optional meta.llm_provider / meta.reasoning_effort). Schema 1.1 reports still load and render. See CHANGELOG.md.

Default LLM mode for a first run: --llm none (deterministic candidate discovery on the bundled tests/patterns tree; no API key). External LLMs are opt-in via --llm or TACS_LLM_PROVIDER.

BYOLLM: bring your own provider; no vendor lock-in. API keys and provider settings may be supplied through process environment variables or a local .env; process environment values take precedence.

Privacy (read this)

There is no hosted code vault, but “local” is not the same as “nothing is retained.”

• Source code context may be sent to the LLM provider you configure only when you opt in (--llm ≠ none, or TACS_LLM_PROVIDER). That can include complete function bodies and, in later analysis stages, file-leading context plus extracted definitions (typedefs, structs, macros).
• tacs scan reads your tree in place; tacs repos clones repositories and keeps them in --cache-dir (default .repo_cache, gitignored) so later runs can reuse them. Delete that directory when you are done.
• Reports are written only where you ask (--out / batch output dirs). Prefer --llm none or local Ollama for sensitive trees. For local runs, keep private inputs under inputs/ and generated artifacts under results/ (both gitignored except their READMEs).

Details: docs/privacy.md.

Principles

• Open source first; model-independent (BYOLLM)
• Explicit environment configuration is the supported path (8 ABI/time_t configs)
• Evidence-oriented pipeline with optional multi-stage LLM analysis
• Human review is authoritative — scanner outputs are candidates for review
• Language surface today is C/C++; the project name and CLI are not limited to C forever
• Default scan scope is common C/C++ sources and headers (**/*.c, **/*.h, **/*.cc, **/*.cpp, **/*.cxx, **/*.hh, **/*.hpp, **/*.hxx); --include replaces that glob list, not the catalog IR allowlist. See docs/usage/RUNNING_FULL_PIPELINE.md.

Limitations

TACS is an AI-assisted review aid, not an authoritative compliance oracle. Treat outputs as candidates for review, not confirmed defects.

TACS is not a completeness checker. A clean scan does not establish that a codebase is free of Y2038, Y2106, or other time-related rollover risks. Detection depends on the current rules, supported language constructs, environment assumptions, analysis heuristics, and—when enabled—the behavior of the selected LLM.

• False positives and false negatives are expected.
• With --llm none, findings are discovery locations (often abstain) — not LLM-validated issues.
• Results vary by model, provider, rules, and --env-config assumptions.
• Wrong or missing environment config can mis-rank risk (prefer an explicit ABI/time_t config).
• tacs detect is experimental and often low-confidence — not ground truth.
• Preprocessor-agnostic scanning means guarded/dead code may still appear as candidates.
• Structural filtering is heuristic today; tree-sitter AST analysis is not implemented in the current release. The .[full] extra installs tree-sitter for that future work, but installing it changes nothing yet — the filter stays a no-op either way.
• No findings ≠ “no time-assurance risk.”
• Human review remains authoritative for severity and remediation before changing production code or ABI choices.

Environment configuration (important)

Scans are only as meaningful as the assumed ABI/time_t model. Prefer an explicit --env-config JSON (see configs/ and docs/env_config.md).

tacs detect can guess among eight configs from Makefiles/CMake. That path is experimental and often low-confidence — use it for convenience, not as ground truth. Batch/repos may fall back when detection is unsure; set an explicit config_override in the JSONL when you know the target.

Quick start

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

tacs version

tacs scan \
  --root tests/patterns \
  --rules src/tacs/rules/y2038_sample_rules.json \
  --env-config configs/example.env_config.json \
  --llm none \
  --out findings.json

Then open findings.json. For providers, troubleshooting, and batch/render, see QUICK_START.md.

Layout

Docs

Start here: QUICK_START.md

Sibling project: time_assurance_doc_scanner (tads) — documentation / standards scanner.

Contributing

See CONTRIBUTING.md. Deferred non-blocking work is tracked in docs/backlog.md. To report a vulnerability, use SECURITY.md (not a public issue).

License

Licensed under the Apache License, Version 2.0.

Copyright (c) 2026 Y2038.com LLC