# Ticket: Support guarded Tool Shed writes on legacy SQLite

Status: active
Type: ticket
Updated: 2026-09-03
Next Action: implement and regression-test bounded legacy-SQLite compatibility in the canonical Tool Shed repository, release it, then upgrade this workspace snapshot
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Campaign: standalone
Campaign Reason: This is an upstream Tool Shed runtime-compatibility defect discovered while executing TKT-0034, not firmware product work.

## Problem

Python 3.11.2 with SQLite 3.39.4 rejects managed document-store writes under `PRAGMA trusted_schema=OFF` with `unsafe use of json_valid()`. The same guarded operation succeeds with Python 3.13.1 and SQLite 3.45.3. Existing compatibility handling covers rebuild and integrity paths but not ordinary managed writes.

## Required Mitigation

1. Centralize managed-write transaction setup so every document-store mutation uses the same guarded compatibility policy.
2. Detect the legacy SQLite capability condition. After verifying the expected schema digest, permit only the narrow compatibility context required for schema constraints using `json_valid()`, and restore `trusted_schema=OFF` immediately in guaranteed cleanup.
3. Preserve fail-closed behavior for an unverified schema, unexpected SQLite errors, interrupted transactions, and any failure to restore the defensive setting.
4. If a supported runtime cannot be made safe, reject it before mutation with a precise Python/SQLite compatibility diagnostic rather than failing mid-operation.

## Acceptance Criteria

- [ ] Managed create, edit, lifecycle, relationship, checkpoint, and rebuild paths succeed safely on Python 3.11 with SQLite 3.39.
- [ ] The same paths continue to succeed on Python 3.13 with SQLite 3.45 or newer.
- [ ] Tests prove schema verification occurs before the compatibility context is enabled.
- [ ] Tests prove `trusted_schema=OFF` is restored after success and every failure path.
- [ ] Unverified or altered schemas remain rejected without mutation.
- [ ] The full Tool Shed release validation passes on the supported runtime matrix.
- [ ] A released Tool Shed version containing the fix is upgradeable into this workspace without modifying project-owned state.

## Interim Operational Mitigation

Use the installed Python 3.13 runtime for Tool Shed document-store mutations until the permanent compatibility fix is released. This is a workaround, not closure evidence.

## Boundaries

- Do not weaken schema-digest enforcement or leave trusted-schema mode enabled.
- Do not develop or patch the disconnected `tool_shed/` snapshot in this firmware repository.
- Do not modify firmware, controller state, media, deployment, or the open release cohort.

## Origin Evidence

Observed during TKT-0034 Work2 execution: Python 3.11.2 / SQLite 3.39.4 failed with `unsafe use of json_valid()`; Python 3.13.1 / SQLite 3.45.3 completed the identical guarded write.