tracecite 0.1.0__tar.gz

tracecite-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# OS, editor, and local graph data
+.DS_Store
+.code-review-graph/
+.device-debug/
+.workbuddy/
+
+# Local environment and signing credentials
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.mobileprovision
+
+# Python environments, caches, and build outputs
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Crash reports, Apple build bundles, and local databases
+*.ips
+*.crash
+*.xcresult
+*.xcarchive
+*.dSYM/
+*.sqlite
+*.db
+
+# TraceCite runtime evidence and filter sidecars
+/.tracecite/
+.filtered/
+*.records.jsonl
+*.hits.jsonl
+*.templates.jsonl
+filter_history.jsonl
+filter_history.jsonl.lock
+*.log
+!tests/fixtures/loghub/*.log
+*.trace
+*.trace.zip
+experiments

tracecite-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 TraceCite Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

tracecite-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include .gitignore
+include README.md
+include README.zh-CN.md
+recursive-include docs *.md
+recursive-include scripts *.py
+recursive-include tests *.py
+recursive-include tests/fixtures *.json *.jsonl *.log

tracecite-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: tracecite
+Version: 0.1.0
+Summary: Extensible evidence runtime for AI agents.
+Author: TraceCite Contributors
+License-Expression: MIT
+Keywords: text,evidence,filter,agents,log-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# TraceCite
+
+**Agent context gateway for AI debugging agents.**
+
+TraceCite controls what log evidence enters the agent's context window.
+It freezes inputs, returns line-addressable evidence pointers, verifies their
+provenance, and keeps the full record on disk for on-demand expansion.
+Domain packages add collection and semantics without modifying the gateway kernel.
+
+TraceCite is **not a replacement for grep** and is **not a token optimizer**.
+Against skilled `grep | head` usage it is typically not cheaper in tokens — it
+is **bounded, auditable, and resistant to over-inference**.
+
+```text
+Raw data -> Core evidence -> Runtime tools -> Your Agent
+                                  ^
+                                  |
+                       Domain extensions
+                  Mobile / CI / third-party
+```
+
+TraceCite is infrastructure **for** Codex, Claude, ChatGPT, or a custom agent.
+It does not embed another LLM agent.
+
+## Install
+
+```bash
+pip install tracecite
+```
+
+The package has no runtime dependencies outside the Python standard library.
+Python 3.10 or newer on Linux and macOS is supported. Windows is not currently
+supported because TraceCite's atomic state locking relies on POSIX `flock`.
+
+## Agent-facing tools
+
+```bash
+tracecite probe ./logs --glob "*.log" --recursive
+tracecite search app.log "timeout|OOM" --regex --snapshot
+tracecite expand .tracecite/snapshots/app.log 120 --before 5 --after 10
+tracecite verify .tracecite/runs/<run-id>/manifest.json
+tracecite run scenario.json
+```
+
+Every command returns deterministic JSON. `status` describes whether execution
+succeeded; `outcome` separately describes what the evidence supports. A valid
+zero-match search is not an execution error and does not prove absence.
+
+Before connecting Codex, Claude, or another host, read the
+[external Agent integration guide](docs/agent-integration.md). It includes the
+tool loop, Result JSON contract, exit codes, safety rules, and a reusable test
+prompt.
+
+The normative [architecture design](docs/architecture.md) defines the common
+investigation protocol, evidence and knowledge model, extension boundaries,
+implementation status, and the rules for future architectural evolution.
+
+The lower-level evidence CLI remains available as `tracecite-core`.
+
+## Stable kernel, public extension boundary
+
+One main distribution contains four logical layers:
+
+- `tracecite_core`: evidence, source, segment, transform, snapshot, manifest,
+  verification, and the low-level plugin SDK.
+- `tracecite.runtime`: scenario, assertion, reporting, result schema, budgets,
+  stop/safety gates, and agent-facing tools.
+- `tracecite.extension`: the versioned third-party registration contract.
+- `tracecite.integrations`: CLI now; MCP and agent-platform adapters later.
+
+Domain semantics do not belong in the main package. The official
+`tracecite-mobile` project is an extension and a contract dogfood project.
+
+## Build an extension without forking TraceCite
+
+```toml
+[project]
+name = "my-company-tracecite"
+dependencies = ["tracecite>=0.1,<0.2"]
+
+[project.entry-points."tracecite.extensions"]
+my_domain = "my_tracecite.extension"
+```
+
+```python
+from tracecite.extension import ExtensionAPI
+from tracecite.runtime import ScenarioRuntime
+
+TRACECITE_EXTENSION_API = "1"
+MY_RUNTIME = ScenarioRuntime(
+    load_profile=load_profile,
+    resolve_scenario_pattern=resolve_pattern,
+)
+
+def register(api: ExtensionAPI) -> None:
+    api.register_runtime("my-domain", MY_RUNTIME)
+```
+
+Loading third-party code is explicit:
+
+```bash
+tracecite extension load
+tracecite run scenario.json --runtime my-domain --load-extensions
+```
+
+Importing `tracecite` alone never executes installed extension registration
+code. Registration conflicts fail by default, API versions are checked, and
+the default Runtime does not grant live-source or action capabilities.
+
+See [the extension contract](docs/extension-contract.md) and the
+[pending domain-validation checklist](docs/validation-checklist.md). Agent
+knowledge uses the separate
+[proposal, verification, and promotion lifecycle](docs/knowledge-governance.md).
+
+## Design principles
+
+- **Bounded output, not bounded cost** — search caps evidence count (agent default 30, configurable via `--max-evidence`); `--max-line-chars` and `--max-output-chars` cap agent-facing text; full artifacts remain on disk.
+- Evidence is traceable, not automatically complete or true.
+- `unknown` and `missing_evidence` are first-class results.
+- Agent conclusions never promote themselves into trusted knowledge.
+- Extensions add capabilities and semantics; Runtime retains execution,
+  evidence, verification, budget, and safety control.
+- Core never imports Runtime or domain packages; Runtime never imports domains.
+
+## Status
+
+The internal Runtime consolidation and compatibility layer are implemented.
+Mobile's public-extension and PlatformBackend contracts pass offline iOS and
+Android fixtures; real-device acceptance and the CI domain pilot remain
+pending. MCP and other agent-platform adapters follow only after those
+contracts are validated.
+
+## License
+
+MIT

tracecite-0.1.0/README.md

@@ -0,0 +1,135 @@
+# TraceCite
+
+**Agent context gateway for AI debugging agents.**
+
+TraceCite controls what log evidence enters the agent's context window.
+It freezes inputs, returns line-addressable evidence pointers, verifies their
+provenance, and keeps the full record on disk for on-demand expansion.
+Domain packages add collection and semantics without modifying the gateway kernel.
+
+TraceCite is **not a replacement for grep** and is **not a token optimizer**.
+Against skilled `grep | head` usage it is typically not cheaper in tokens — it
+is **bounded, auditable, and resistant to over-inference**.
+
+```text
+Raw data -> Core evidence -> Runtime tools -> Your Agent
+                                  ^
+                                  |
+                       Domain extensions
+                  Mobile / CI / third-party
+```
+
+TraceCite is infrastructure **for** Codex, Claude, ChatGPT, or a custom agent.
+It does not embed another LLM agent.
+
+## Install
+
+```bash
+pip install tracecite
+```
+
+The package has no runtime dependencies outside the Python standard library.
+Python 3.10 or newer on Linux and macOS is supported. Windows is not currently
+supported because TraceCite's atomic state locking relies on POSIX `flock`.
+
+## Agent-facing tools
+
+```bash
+tracecite probe ./logs --glob "*.log" --recursive
+tracecite search app.log "timeout|OOM" --regex --snapshot
+tracecite expand .tracecite/snapshots/app.log 120 --before 5 --after 10
+tracecite verify .tracecite/runs/<run-id>/manifest.json
+tracecite run scenario.json
+```
+
+Every command returns deterministic JSON. `status` describes whether execution
+succeeded; `outcome` separately describes what the evidence supports. A valid
+zero-match search is not an execution error and does not prove absence.
+
+Before connecting Codex, Claude, or another host, read the
+[external Agent integration guide](docs/agent-integration.md). It includes the
+tool loop, Result JSON contract, exit codes, safety rules, and a reusable test
+prompt.
+
+The normative [architecture design](docs/architecture.md) defines the common
+investigation protocol, evidence and knowledge model, extension boundaries,
+implementation status, and the rules for future architectural evolution.
+
+The lower-level evidence CLI remains available as `tracecite-core`.
+
+## Stable kernel, public extension boundary
+
+One main distribution contains four logical layers:
+
+- `tracecite_core`: evidence, source, segment, transform, snapshot, manifest,
+  verification, and the low-level plugin SDK.
+- `tracecite.runtime`: scenario, assertion, reporting, result schema, budgets,
+  stop/safety gates, and agent-facing tools.
+- `tracecite.extension`: the versioned third-party registration contract.
+- `tracecite.integrations`: CLI now; MCP and agent-platform adapters later.
+
+Domain semantics do not belong in the main package. The official
+`tracecite-mobile` project is an extension and a contract dogfood project.
+
+## Build an extension without forking TraceCite
+
+```toml
+[project]
+name = "my-company-tracecite"
+dependencies = ["tracecite>=0.1,<0.2"]
+
+[project.entry-points."tracecite.extensions"]
+my_domain = "my_tracecite.extension"
+```
+
+```python
+from tracecite.extension import ExtensionAPI
+from tracecite.runtime import ScenarioRuntime
+
+TRACECITE_EXTENSION_API = "1"
+MY_RUNTIME = ScenarioRuntime(
+    load_profile=load_profile,
+    resolve_scenario_pattern=resolve_pattern,
+)
+
+def register(api: ExtensionAPI) -> None:
+    api.register_runtime("my-domain", MY_RUNTIME)
+```
+
+Loading third-party code is explicit:
+
+```bash
+tracecite extension load
+tracecite run scenario.json --runtime my-domain --load-extensions
+```
+
+Importing `tracecite` alone never executes installed extension registration
+code. Registration conflicts fail by default, API versions are checked, and
+the default Runtime does not grant live-source or action capabilities.
+
+See [the extension contract](docs/extension-contract.md) and the
+[pending domain-validation checklist](docs/validation-checklist.md). Agent
+knowledge uses the separate
+[proposal, verification, and promotion lifecycle](docs/knowledge-governance.md).
+
+## Design principles
+
+- **Bounded output, not bounded cost** — search caps evidence count (agent default 30, configurable via `--max-evidence`); `--max-line-chars` and `--max-output-chars` cap agent-facing text; full artifacts remain on disk.
+- Evidence is traceable, not automatically complete or true.
+- `unknown` and `missing_evidence` are first-class results.
+- Agent conclusions never promote themselves into trusted knowledge.
+- Extensions add capabilities and semantics; Runtime retains execution,
+  evidence, verification, budget, and safety control.
+- Core never imports Runtime or domain packages; Runtime never imports domains.
+
+## Status
+
+The internal Runtime consolidation and compatibility layer are implemented.
+Mobile's public-extension and PlatformBackend contracts pass offline iOS and
+Android fixtures; real-device acceptance and the CI domain pilot remain
+pending. MCP and other agent-platform adapters follow only after those
+contracts are validated.
+
+## License
+
+MIT

tracecite-0.1.0/README.zh-CN.md

@@ -0,0 +1,101 @@
+# TraceCite
+
+**面向 AI 调试 Agent 的可扩展证据运行时。**
+
+TraceCite 为大体量、持续变化的日志提供有界且可校验来源的证据视图。它会冻结输入、返回证据引用、校验证据来源，并允许第三方在不修改 TraceCite 源码的情况下增加领域能力。
+
+```text
+原始数据 -> Core 证据层 -> Runtime 工具层 -> 外部 Agent
+                               ^
+                               |
+                         领域扩展包
+                    Mobile / CI / 第三方
+```
+
+TraceCite 是给 Codex、Claude、ChatGPT 或自研 Agent 使用的基础设施，内部不再套一层 LLM Agent。
+
+## 安装与使用
+
+```bash
+pip install tracecite
+
+tracecite probe ./logs --glob "*.log" --recursive
+tracecite search app.log "timeout|OOM" --regex --snapshot
+tracecite expand .tracecite/snapshots/app.log 120 --before 5 --after 10
+tracecite verify .tracecite/runs/<run-id>/manifest.json
+tracecite run scenario.json
+```
+
+运行环境为 Python 3.10 及以上版本，支持 Linux 和 macOS。当前暂不支持 Windows，
+因为 TraceCite 的原子状态锁依赖 POSIX `flock`。除 Python 标准库外无运行时依赖。
+
+所有命令返回确定性的 JSON。`status` 表示执行是否成功，`outcome` 单独表示证据支持什么。零命中是合法结果，不等于“问题没有发生”。
+
+准备让 Codex、Claude 或其他自研 Agent 直接测试时，请先阅读[外部 Agent 接入指南](docs/agent-integration.zh-CN.md)。其中包含调用顺序、Result JSON、退出码、安全规则和可复制的测试 Prompt。
+
+规范性的[架构设计](docs/architecture.zh-CN.md)定义了通用调查协议、证据与知识模型、扩展边界、当前实现状态以及后续架构演进的维护规则。
+
+低层证据命令仍可通过 `tracecite-core` 使用。
+
+## 一个主项目，清晰的逻辑边界
+
+- `tracecite_core`：Source、Segment、Transform、Evidence、Snapshot、Manifest、Verify 与底层 Plugin SDK。
+- `tracecite.runtime`：Scenario、Assertion、Reporting、Result schema、预算、安全门禁和 Agent 工具。
+- `tracecite.extension`：有版本的第三方扩展契约。
+- `tracecite.integrations`：目前提供 CLI；MCP、Codex Skill 等适配器后续再接。
+
+领域语义不进入主包。`tracecite-mobile` 是独立的官方扩展，也是 Extension API 的真实验证项目。
+
+## 不改主库，增加自己的能力
+
+第三方包只依赖一个公开发行包：
+
+```toml
+[project]
+name = "my-company-tracecite"
+dependencies = ["tracecite>=0.1,<0.2"]
+
+[project.entry-points."tracecite.extensions"]
+my_domain = "my_tracecite.extension"
+```
+
+```python
+from tracecite.extension import ExtensionAPI
+from tracecite.runtime import ScenarioRuntime
+
+TRACECITE_EXTENSION_API = "1"
+MY_RUNTIME = ScenarioRuntime(
+    load_profile=load_profile,
+    resolve_scenario_pattern=resolve_pattern,
+)
+
+def register(api: ExtensionAPI) -> None:
+    api.register_runtime("my-domain", MY_RUNTIME)
+```
+
+加载第三方代码是显式动作：
+
+```bash
+tracecite extension load
+tracecite run scenario.json --runtime my-domain --load-extensions
+```
+
+仅仅 `import tracecite` 不会执行第三方注册代码。API 版本会校验，注册冲突默认失败，默认 Runtime 不授权 live source 和 action。
+
+详细约束见[扩展契约](docs/extension-contract.md)；第 7 步已完成 Mobile 离线契约验证，真机与 CI 试点仍待执行，具体流程见[领域验证清单](docs/validation-checklist.md)。Agent 知识写入遵循独立的[提案、验证与晋升流程](docs/knowledge-governance.zh-CN.md)。
+
+## 核心原则
+
+- Evidence 可追溯，但不自动等于完整事实或真相。
+- `unknown` 和 `missing_evidence` 是一等结果。
+- Agent 自己生成的结论不能自动晋升为可信 Knowledge。
+- Extension 提供能力和领域语义；Runtime 保留执行、预算、验证和安全控制权。
+- Core 不导入 Runtime 或领域；Runtime 不导入 Mobile/CI。
+
+## 当前状态
+
+主项目 Runtime 合并与旧 API 兼容层已实现。Mobile 公共扩展和 PlatformBackend 契约已通过 iOS/Android 离线 fixture；真机验收与 CI 领域试点仍待执行，通过前不推进 MCP 或其他 Agent 平台 Adapter。
+
+## License
+
+MIT

tracecite-0.1.0/docs/adr/README.md

@@ -0,0 +1,46 @@
+# Architecture Decision Records
+
+Use an Architecture Decision Record (ADR) for an incompatible architectural change or a decision with a long-lived trade-off. Small internal refactors that preserve the contracts in `docs/architecture.md` do not require an ADR.
+
+Name records `NNNN-short-title.md`. ADRs are immutable after acceptance except for status and links; superseding decisions create a new ADR.
+
+Required template:
+
+```markdown
+# NNNN: Decision title
+
+- Status: proposed | accepted | superseded | rejected
+- Date: YYYY-MM-DD
+- Owners:
+- Supersedes:
+- Superseded by:
+
+## Context
+
+What problem, constraints, and evidence require a decision?
+
+## Decision
+
+What is changing, and which architectural invariant or public contract is affected?
+
+## Alternatives considered
+
+What credible alternatives were evaluated and why were they not selected?
+
+## Consequences
+
+Positive effects, costs, risks, compatibility impact, and operational impact.
+
+## Migration and validation
+
+Schema/API versioning, rollout, rollback, tests, and at least two domain cases when a main-package boundary changes.
+
+## Documentation updates
+
+List the architecture, integration, extension, knowledge, and validation documents updated with this decision.
+```
+
+Both [`docs/architecture.md`](../architecture.md) and
+[`docs/architecture.zh-CN.md`](../architecture.zh-CN.md) remain the current
+architecture contract. ADRs explain why that contract changed; they do not
+replace it.