Parent scope: package runtime.
Core owns product semantics over config, Context, queries and snapshot mechanisms. CLI/API adapters consume its results and errors; presentation stays in adapters.
| Files | Responsibility |
|---|---|
focus_service.py |
Resolve/validate database and device; explicit project/global focus writes |
context_cache.py |
Bounded persistent Context LRU with resolved-path and file-signature invalidation |
query_service.py |
Catalog contracts, focus/device selection, executor reuse, completeness and timeout budget |
capability_service.py, overview_service.py |
Full catalog and read-only database/device/event-bound/import-metadata probes |
report_service.py |
Compose named queries into peak-memory reports rather than duplicate SQL |
import_service.py, import_metadata.py |
Trusted-input import validation, source/cache identity, metadata, optional focus |
snapshot_import_backend.py |
Runtime adapter, temporary database, publication and rollback resources |
split_service.py |
Strategy/device validation, staging, replay validation and exclusive directory publication |
skill_service.py |
Skill discovery, status, install/upgrade/uninstall destination policy |
models.py, errors.py |
Shared dataclass results and normalized domain failures |
error_codes.py, json_codec.py |
Stable JSON error classification/hints and serializable envelopes |
- A caller-supplied
ContextCacheis borrowed. Checkis not None, since an empty cache is falsy.QueryServiceandOverviewServiceclose only owned caches;ReportServiceowns and closes its internally constructed query service. QueryService.close()releases its executor references and owned cache but allows reuse. This differs from terminalSnapshotAnalyzer.close().- Cache keys are resolved paths; the signature is
(mtime_ns, inode, size). Replacement or eviction closes the old Context. Executor reuse follows the actual Context instance; invalidation must not reuse an executor bound to an evicted connection. - Finite trailing pages probe one extra row. A full inner
top_nwindow is conservatively incomplete too. Keephas_more,truncated,total, andtotal_is_exactconsistent; exact totals are opt-in and share the page query's timeout budget.PT_SNAP_QUERY_TIMEOUTis a time bound, not a row limit.
Import runs the backend in a temporary directory, then writes/validates metadata before replacing the destination. When focus is requested and a destination already exists, rollback uses a copied backup held by a secure file descriptor until the post-publication action succeeds. This is a backup copy, not a hard link. Handle short/zero writes and close descriptors on every failure path.
Normal post-publication failure restores the previous destination (or removes a
new one). If rollback itself fails, preserve recovery evidence and report that
failure explicitly; never claim unconditional atomic restoration after I/O failure.
See tests/core/test_import_backend_failures.py and test_import_service.py.
Split requires exactly one positive slices/max_entries strategy and an absent
destination. It validates selected-device slices by replay before publication;
concurrent destination creation must fail rather than replace another result.
- Default catalog precedence:
PT_SNAP_SKILLS_DIR, repositoryskills/, then packagedbundled_skills/; an explicit servicecatalog_diroverrides this. - Default install targets shared
~/.agents/skillsand independent Claude skills (~/.claude/skillsor$CLAUDE_CONFIG_DIR/skills). Explicit Cursor/Codex targets retain their native extras;--diris a separate custom destination. - List reports
installed,outdated,missingacross selected locations; filesystem status does not prove the current host loaded the skill. - Unfiltered CLI uninstall discovers all built-in hosts and both scopes, removing
installed/outdated copies containing
SKILL.md. A same-named non-skill path aborts the entire operation before deletion. Explicit target/project/directory filters retain narrower destinations. uninstall_skills(all_locations=True)rejectshosts,dest_dir, and scope other thanuser. Keep this service constraint aligned withcli_skills.py.
Use service tests for the owning suite. Shared
result/error changes also require tests/test_contract_cli_api.py and JSON
contracts; template metadata must flow through template_info_to_dict to both
adapters. Keep the models.py Any/Unknown type gates intact. Runtime changes
also follow snapshot guidance, and skill content changes
follow authoring/evaluation.