diff --git a/README.md b/README.md index cef8326..51cd231 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,8 @@ sdl doctor --json - Ollama manifests and blobs directories exist - LM Studio models directory exists - Hard-link filesystem/volume compatibility +- Hard-link permission on blobs (a real link is created and removed again, catching restrictions such as Linux `fs.protected_hardlinks`) +- LM Studio model inventory (`lms ls --json`; required to verify projector bundles) - Discovered Ollama models - Blob presence validation - GGUF header validation diff --git a/docs/research/branch-reliability-audit.md b/docs/research/branch-reliability-audit.md new file mode 100644 index 0000000..8174bb7 --- /dev/null +++ b/docs/research/branch-reliability-audit.md @@ -0,0 +1,198 @@ +# Branch reliability audit + +**Date:** 2026-09-02 +**Scope:** `main` (`221229d`), `stabilize-sync-lifecycle` (`3d5c60b`), and +`support-artifact-bundles` (`1090dbc`) +**Method:** read-only `git show`/`git diff` inspection, the existing worktrees, +repository tests, small temporary-directory probes, and primary platform sources. + +## Executive conclusion + +The proposed four fixes are well chosen, but the bundles branch has two additional +merge blockers: + +- Re-pulling a vision bundle when only one artifact digest changes reuses the + unchanged artifact from the old digest-keyed LM Studio directory and imports + the changed artifact into the new directory. The split can either fail forever + or, worse, be falsely confirmed against the old bundle. +- A valid manifest that lists the projector before the model imports the + projector first, then tries to persist a projector-only partial record. + `primary_artifact` raises `StopIteration`, aborting the entire batch. + +Recommended pre-merge order: + +1. **P1:** normalize bundle imports to model-first and never serialize a partial + `SyncRecord` without exactly one model artifact. +2. **P1:** keep every artifact of a changed vision bundle co-located; do not reuse + an unchanged artifact from a different `import_user_repo` without importing or + linking it into the new repository. +3. **P1:** translate stale-alias `unlink()` and staging `mkdir()` failures to the + per-model `RuntimeError` result, with two-model continuation tests. +4. **P2:** make bundles `status()` degrade to pending when `lms ls --json` fails. +5. **P2:** read state with `utf-8-sig`, with a real-record regression test. +6. **P2/platform:** add an actual hard-link permission probe and actionable Linux + error; `st_dev` equality alone is insufficient. +7. **P2/conditional correctness:** make `same_file()` return false when either + inode/file identifier is zero. A size comparison is only an extra rejection + check, not proof that equal-sized files are the same file. + +The full existing suites pass (main 117, stabilize 135, bundles 156), so the +listed failures are coverage gaps rather than known failing tests. + +## Branch relationship + +`support-artifact-bundles` is not an alternative to `stabilize-sync-lifecycle`: +its merge base with stabilize is exactly `3d5c60b`, so bundles contains all of +stabilize plus `7bbf601` and `1090dbc`. Review and merge planning should treat +the work as one stack. + +## Verified bugs + +| Claim | Verdict and evidence | +|---|---| +| Batch abort on alias filesystem errors | **Confirmed on all three refs.** The stale `unlink()` and `mkdir()` occur before the `try` that wraps only `os.link()`: [main 198-204](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/syncer.py#L198-L204), [stabilize 231-237](https://github.com/ensevengg/StudioLink/blob/3d5c60b1bc6b3927b1fb2be196d0fd87c591526c/src/studiolink/syncer.py#L231-L237), [bundles 457-463](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L457-L463). Callers catch only `RuntimeError` ([bundles 194-207](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L194-L207)), while the outer batch loop has no catch ([74-80](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L74-L80)). A raw `PermissionError`/`FileExistsError` therefore aborts the batch. Existing isolation tests cover only LM Studio failures ([tests 436-469](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/tests/test_syncer.py#L436-L469)). | +| Bundles `status` crashes when `lms` is broken | **Confirmed, bundles only.** Status conditionally calls `list_models()` with no guard ([77-99](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/service.py#L77-L99)); the adapter translates execution and JSON failures to `LMStudioError` ([66-110](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/lmstudio_adapter.py#L66-L110), [149-176](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/lmstudio_adapter.py#L149-L176)). `inventory=None` is already interpreted as unsynced/pending for projector records ([service 392-397](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/service.py#L392-L397)), so the proposed fallback fits the current model. Current status tests cover an empty inventory, not an inventory exception ([tests 430-461](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/tests/test_service.py#L430-L461)). | +| UTF-8 BOM drops state | **Confirmed on all three refs.** `_load_raw()` uses `encoding="utf-8"` and turns the resulting JSON decode error into `{}`/“Starting fresh”: [main 72-82](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/state.py#L72-L82), [bundles 71-81](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/state.py#L71-L81). Sync then sees no records and re-imports. `utf-8-sig` on reads is the narrow correct fix; writes can remain UTF-8. No BOM regression test exists. | + +## Additional bundles merge blockers + +### Projector-first manifests abort the batch + +The adapter preserves the manifest's model/projector layer order +([adapter 133-162](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/ollama_adapter.py#L133-L162)), +and sync imports in that order. After *each* imported artifact it creates and +saves a partial record ([syncer 245-265](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L245-L265)). +But serialization unconditionally resolves `primary_artifact` +([models 211-217](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/models.py#L211-L217), +[240-248](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/models.py#L240-L248)). +A projector-only partial has no primary, so `next(...)` raises `StopIteration`; +the outer batch loop does not catch it. + +A temporary probe with layers `[projector C, model A]` produced artifact order +`['projector', 'model']`, imported only the projector, then raised +`StopIteration`. Normalize supported artifacts to model-first before import (or +defer partial persistence until a primary exists) and add both a standalone and +two-model batch regression. The current fixture's model-first order does not +establish a general ordering invariant. + +### Changed vision bundles are split across old and new repositories + +The bundles branch keys `import_user_repo` by *all* artifact digest prefixes +([models 120-129](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/models.py#L120-L129)). +On re-sync it reuses an artifact solely by `(role, digest)` and target existence +([syncer 146-188](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L146-L188)), +but imports a changed artifact into the newly computed repository +([190-217](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L190-L217)). +LM Studio pairing requires both files in one directory +([the branch's end-to-end validation](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/docs/research/multi-artifact-validation.md#L8-L13)), +and reconciliation tests the new primary path for vision +([374-397](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L374-L397)). + +A temporary-directory probe synced `(model=A, projector=C)`, changed only the +model to `B`, then synced again. The first sync was `synced`; the second imported +one file and returned `error: LM Studio did not index the projector bundle as +vision-capable`. State pointed to: + +```text +.../llava--bundle-bbbbbbbbbbbb-cccccccccccc/ +.../llava--bundle-aaaaaaaaaaaa-cccccccccccc/ +``` + +Retry reuses both split targets and repeats the same error. The inverse change is +more dangerous: with `(model=A, projector=C)` already installed, changing only +the projector to `D` reuses the old primary in the old `A-C` directory (where old +projector C remains), imports D alone into the new `A-D` directory, then confirms +vision against the *old* A-C inventory entry. State and `status` can therefore +say synced while LM Studio still pairs A with stale projector C. + +The fix should make reuse conditional on the target's parent being the current +destination, or re-import/re-link every required artifact into the new bundle +directory. Add tests for changing only the primary digest and only the projector +digest, asserting co-location and the exact inventory path used for confirmation. + +## Conditional platform risks + +### Linux protected hard links + +**Strongly substantiated; the kernel mechanism was reproduced in WSL, but not +against an installed Ollama service.** With `fs.protected_hardlinks=1`, a +hard-link attempt by an unprivileged user to a root-owned `0644` source was +denied, while the same probe succeeded after the source was changed to `0666`. +That isolates the expected ownership/write-permission mechanism; the probe host +did not have a real Ollama installation. Stabilize changes the Linux default +store to `/usr/share/ollama/.ollama/models` +([config 18-21](https://github.com/ensevengg/StudioLink/blob/3d5c60b1bc6b3927b1fb2be196d0fd87c591526c/src/studiolink/config.py#L18-L21)). +Ollama's official system-service instructions create and run as the dedicated +`ollama` user ([official Linux docs](https://github.com/ollama/ollama/blob/205a0426905d45f5ed0d120f3c671e3573e01b41/docs/linux.mdx#adding-ollama-as-a-startup-service-recommended)), +and Ollama explicitly chmods newly created blobs to `0644` +([official source](https://github.com/ollama/ollama/blob/205a0426905d45f5ed0d120f3c671e3573e01b41/manifest/layer.go#L52-L59)). +With `fs.protected_hardlinks=1`, Linux rejects links by users who neither own nor +have read/write access to the source +([kernel documentation](https://docs.kernel.org/admin-guide/sysctl/fs.html#protected-hardlinks)). + +StudioLink always first calls `os.link(blob, alias)`, including copy mode +([stabilize 208-238](https://github.com/ensevengg/StudioLink/blob/3d5c60b1bc6b3927b1fb2be196d0fd87c591526c/src/studiolink/syncer.py#L208-L238)). +The doctor check compares only `st_dev` values +([service 323-348](https://github.com/ensevengg/StudioLink/blob/3d5c60b1bc6b3927b1fb2be196d0fd87c591526c/src/studiolink/service.py#L323-L348)), +so a typical single-filesystem machine can pass while link creation returns +`EPERM`; copy staging can also fail earlier if the user cannot create +`.studiolink-imports` under the Ollama-owned store. An actual reversible +`os.link()` probe using a real blob and each relevant destination is materially +better than a permission-bit or volume-only check. The error should explain +ownership/`protected_hardlinks` and the supported remediation; a doctor warning +alone does not make the default hard-link workflow work. + +### Zero/unknown inode identifiers + +**The code defect is confirmed; the exact exFAT/FAT incidence was not reproduced.** +Every ref treats equal `(st_dev, st_ino)` as conclusive +([bundles 34-43](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L34-L43)). +Python only promises uniqueness when `st_ino` is nonzero +([official `stat_result` docs](https://docs.python.org/3/library/os.html#os.stat_result)). +Thus two distinct files reported as `(same device, 0)` are misclassified and a +wrong pre-existing alias can be reused. Return false if either identifier is +zero. Comparing `st_size` is useful as another mismatch check, but equal sizes +do not establish identity and therefore do not fully fix stale-weight reuse. + +## Design-level reliability gaps + +| Claim | Verdict and refinement | +|---|---| +| No fsync before replace | **Confirmed on all refs.** State is written with `Path.write_text()` and immediately replaced, with no file flush/fsync and no parent-directory fsync ([bundles 63-69](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/state.py#L63-L69)). Atomic namespace replacement is not a power-loss durability guarantee. A robust sequence is unique temp file -> flush/fsync file -> replace -> fsync parent where supported. | +| No locking/fixed temp | **Confirmed on all refs.** Every writer uses `state.json.tmp` ([bundles 67-69](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/state.py#L67-L69)) and read/modify/write operations have no inter-process lock. Concurrent commands can lose updates; the shared temp name also permits replace races and `FileNotFoundError`. Use a state-scoped inter-process lock around the full transaction and unique same-directory temp files. | +| Prune ignores copy staging | **Confirmed on both improvement refs.** Copy aliases live under `/.studiolink-imports` ([bundles 421-433](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L421-L433)), while prune scans only `config.import_staging_dir` ([service 176-213](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/service.py#L176-L213)). A process crash or cleanup failure can therefore leave a hard link that pins bytes indefinitely. | +| Dry-run has filesystem side effects | **Refine.** It really does create a staging directory and hard link before invoking `lms --dry-run`; it is not intrinsically read-only ([bundles 194-227](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L194-L227)). However, successful stabilize/bundles runs unlink the alias *and rmdir the staging leaf* ([399-419](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L399-L419)); because a real blob implies `ollama_models_dir` already exists, successful copy dry-runs do not normally leave parent directories. Persistent empty `.studiolink-imports` is an error/crash path (notably `mkdir` succeeds then `os.link` fails), not the normal success path. Main does leave its state staging directory after a successful dry-run because it unlinks only the file ([main 151-159](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/syncer.py#L151-L159)). | +| Missing source blob: text skipped, vision errors | **Confirmed in bundles.** A synced text model returns before the stale check, while projector models deliberately bypass that return and reach the stale error ([syncer 104-126](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L104-L126)). Choose and test one policy; reporting stale consistently is least surprising. | +| Old LM Studio imports are orphaned | **Confirmed.** Filenames include digest prefixes ([models 139-149](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/models.py#L139-L149)); vision repositories include all digest prefixes ([120-129](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/models.py#L120-L129)). Prune removes staging aliases and state only, never LM Studio targets. Text re-pulls leave old digest files; vision re-pulls leave old bundle directories. Deletion needs an explicit ownership/safety policy because those directories are user-visible LM Studio data. | +| Upgrade prerelease comparison | **Confirmed, unchanged.** `_version_tuple()` strips non-digits per dotted component, so `0.2.1rc1` becomes `(0, 2, 11)` ([CLI 320-325](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/cli.py#L320-L325)); the test codifies the faulty behavior ([tests 240-241](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/tests/test_cli.py#L240-L241)). Use standards-aware version parsing. | +| Pip upgrade unpinned | **Confirmed, unchanged.** The command installs unpinned `studiolink --upgrade` after separately reading a reported version ([CLI 272-301](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/cli.py#L272-L301)). Pin the fetched version if the success message is meant to be authoritative. | +| ANSI/control-sequence spoofing | **Confirmed, print-only, unchanged.** Canonical names derived from manifest path components are printed directly by scan/sync/status ([CLI 183-188](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/cli.py#L183-L188), [206-208](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/cli.py#L206-L208), [223-232](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/cli.py#L223-L232)). JSON output remains machine-safe encoding; sanitize controls in terminal rendering. | + +## “Probed safe” claims + +| Claim | Verdict and scope | +|---|---| +| Prune is symlink-safe | **Destructive action is safe, wording needs nuance.** `is_file()`, `same_file()`, and `stat()` follow a planted symlink for metadata, but deletion is `path.unlink()`, which removes the link entry rather than its target ([bundles service 179-204](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/service.py#L179-L204)). So “target never deleted” is accurate; “never followed” is not. An expected-name symlink to the current blob can also satisfy `same_file()` and be preserved rather than unlinked. | +| `--direct` never deletes the Ollama blob | **Confirmed.** Direct mode uses the blob as `alias_path` ([bundles 190-192](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L190-L192)), and cleanup explicitly excludes direct mode ([399-413](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L399-L413)). | +| Ctrl-C cleans temporary aliases | **Confirmed for ordinary Python interruption.** Import is inside `try/finally`, so `KeyboardInterrupt` runs cleanup before propagating ([bundles 209-227](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L209-L227)). This cannot cover hard process termination or power loss. | +| Concurrent alias-creation race is non-corrupting | **Confirmed for the absent-alias race.** One `os.link` wins; the other receives an `OSError` translated to `RuntimeError` ([bundles 459-464](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L459-L464)). It fails one model rather than overwriting content. This does not make state writes concurrency-safe. | +| Artifact ordering is consistent | **Refuted as a safety claim.** The adapter and syncer consistently preserve *manifest* order ([adapter 133-162](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/ollama_adapter.py#L133-L162), [syncer 158-188](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/syncer.py#L158-L188)), but they do not enforce model-first. A projector-first manifest crashes while saving the first partial record, as detailed above. Normalize semantic order rather than relying on the current fixture. | +| Schema v2 downgrades cleanly to 0.2.0 | **No-crash compatibility confirmed, but it is lossy.** Bundles keeps legacy primary fields at the record top level ([models 240-260](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/models.py#L240-L260)), and 0.2.0 ignores extra fields while parsing ([main models 117-129](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/models.py#L117-L129)). But the next 0.2.0 bulk `save()` serializes legacy records and schema 1, discarding projector/vision metadata ([main state 44-70](https://github.com/ensevengg/StudioLink/blob/221229ddd9df6176134a1da695fd82c0a21499cb/src/studiolink/state.py#L44-L70)). Safe means “does not crash,” not round-trip preservation. | +| Corrupt manifest JSON protects aliases | **Confirmed on stabilize and bundles, not main.** Invalid JSON becomes an `INVALID` model rather than disappearing ([bundles adapter 116-126](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/ollama_adapter.py#L116-L126)); prune protects aliases for every unready model with a record ([service 163-183](https://github.com/ensevengg/StudioLink/blob/1090dbcb80436e3a0a4be4d7bc3db95b8b853acf/src/studiolink/service.py#L163-L183)). Main has no `unready_names` protection and can remove that alias. | + +## Test additions worth requiring with the fixes + +- Two-model batches where the first alias hits `PermissionError` from `mkdir()` + and from stale-alias `unlink()`; the second model must still sync. +- Vision `status()` where `list_models()` raises `LMStudioError`; output must be + pending and the command successful. +- A BOM-prefixed state file containing a real record, not just empty JSON. +- Projector-first valid manifests, including a two-model batch; the model must be + imported first or no invalid projector-only partial may be saved. +- Vision re-pulls changing only the model digest and only the projector digest; + all imported paths must share the current bundle parent and reconciliation + must succeed. +- Mocked zero inode/file identifiers for two distinct files; `same_file()` must + return false even when their sizes match. +- Copy dry-run/link-failure cleanup and prune coverage for + `.studiolink-imports` leftovers. diff --git a/src/studiolink/__init__.py b/src/studiolink/__init__.py index 8fe341e..70e1644 100644 --- a/src/studiolink/__init__.py +++ b/src/studiolink/__init__.py @@ -2,4 +2,4 @@ __all__ = ["__version__"] -__version__ = "0.3.0" +__version__ = "0.3.1" diff --git a/src/studiolink/cli.py b/src/studiolink/cli.py index 6efc2ab..25c800e 100644 --- a/src/studiolink/cli.py +++ b/src/studiolink/cli.py @@ -3,6 +3,7 @@ import argparse import json import logging +import re import subprocess import sys import urllib.request @@ -297,7 +298,9 @@ def run_upgrade(args: argparse.Namespace, service: StudioLinkService) -> int: "-m", "pip", "install", - "studiolink", + # Pin the version we just reported so the success message cannot + # describe a different release than the one pip actually installed. + f"studiolink=={latest}", "--upgrade", "--quiet", ] @@ -329,8 +332,10 @@ def run_upgrade(args: argparse.Namespace, service: StudioLinkService) -> int: def _version_tuple(version: str) -> tuple[int, ...]: parts: list[int] = [] for piece in version.split("."): - digits = "".join(ch for ch in piece if ch.isdigit()) - parts.append(int(digits) if digits else 0) + # Compare only the leading numeric run of each component so that + # pre-release suffixes like "1rc1" do not concatenate into 11. + match = re.match(r"\d+", piece) + parts.append(int(match.group()) if match else 0) return tuple(parts) diff --git a/src/studiolink/models.py b/src/studiolink/models.py index 73f065e..8eccad4 100644 --- a/src/studiolink/models.py +++ b/src/studiolink/models.py @@ -210,10 +210,11 @@ class SyncRecord: @property def primary_artifact(self) -> SyncedArtifact: - return next( - artifact - for artifact in self.artifacts - if artifact.role is ArtifactRole.MODEL + for artifact in self.artifacts: + if artifact.role is ArtifactRole.MODEL: + return artifact + raise ValueError( + f"sync record for {self.canonical_name!r} has no model artifact" ) # Compatibility properties for callers and schema-v1 JSON consumers. diff --git a/src/studiolink/ollama_adapter.py b/src/studiolink/ollama_adapter.py index f5783f8..9ff0250 100644 --- a/src/studiolink/ollama_adapter.py +++ b/src/studiolink/ollama_adapter.py @@ -156,6 +156,10 @@ def _parse_manifest(self, manifest_path: Path) -> OllamaModel | None: for role in sorted(unsupported_roles): issues.append(f"Ollama {role} layers are not supported") + # Import order is semantic: partial sync records must always contain + # the model artifact, so normalize model layers before projectors + # regardless of the order the manifest lists them in. + artifact_layers.sort(key=lambda entry: entry[2] is not ArtifactRole.MODEL) artifacts = tuple( self._parse_artifact(layer, role, index) for index, layer, role in artifact_layers diff --git a/src/studiolink/service.py b/src/studiolink/service.py index b736c48..1fab354 100644 --- a/src/studiolink/service.py +++ b/src/studiolink/service.py @@ -7,7 +7,7 @@ from typing import TYPE_CHECKING from studiolink.config import StudioLinkConfig -from studiolink.lmstudio_adapter import LMStudioAdapter +from studiolink.lmstudio_adapter import LMStudioAdapter, LMStudioError from studiolink.models import ( ArtifactRole, DoctorCheck, @@ -85,7 +85,18 @@ def status(self) -> list[StatusEntry]: and records.get(model.canonical_name) is not None for model in models ) - inventory = self.lmstudio.list_models() if needs_inventory else None + inventory: tuple[LMStudioModel, ...] | None = None + if needs_inventory: + try: + inventory = self.lmstudio.list_models() + except LMStudioError as exc: + # A broken lms must not take the whole status command down; + # without inventory evidence vision bundles read as pending. + logger.warning( + "Could not list LM Studio models (%s); projector bundles " + "will be reported as pending", + exc, + ) return [ StatusEntry( model=model, @@ -174,8 +185,20 @@ def prune(self, *, dry_run: bool = False) -> PruneReport: } alias_results: list[PruneResult] = [] - staging = self.config.import_staging_dir - if staging.exists(): + # Copy mode stages temporary aliases inside the Ollama store; they are + # removed after each import, so anything found there survived a crash + # or a cleanup failure and pins blob space until it is swept. + staging_dirs = list( + dict.fromkeys( + [ + self.config.import_staging_dir, + self.config.ollama_models_dir / ".studiolink-imports", + ] + ) + ) + for staging in staging_dirs: + if not staging.exists(): + continue for path in sorted(staging.iterdir()): if not path.is_file(): continue @@ -267,6 +290,7 @@ def doctor(self) -> list[DoctorCheck]: str(self.config.lmstudio_models_dir), ), self._volume_compatibility_check(), + self._hard_link_permission_check(), ] try: @@ -297,6 +321,19 @@ def doctor(self) -> list[DoctorCheck]: logger.debug("Doctor: LM Studio capabilities check failed: %s", exc) checks.append(DoctorCheck("lm studio import capabilities", False, str(exc))) + try: + inventory = self.lmstudio.list_models() + checks.append( + DoctorCheck( + "lm studio model inventory", + True, + f"{len(inventory)} model(s) indexed", + ) + ) + except Exception as exc: + logger.debug("Doctor: LM Studio inventory check failed: %s", exc) + checks.append(DoctorCheck("lm studio model inventory", False, str(exc))) + models = self.scan() checks.append( DoctorCheck( @@ -373,6 +410,61 @@ def _volume_compatibility_check(self) -> DoctorCheck: ) return DoctorCheck("hard-link volume compatibility", ok, details) + def _hard_link_permission_check(self) -> DoctorCheck: + """Probe that a real blob can actually be hard-linked into staging. + + Same-volume checks (st_dev) cannot catch policies such as Linux + fs.protected_hardlinks, which blocks linking a blob the user cannot + write - the typical layout when Ollama runs as a system service. The + probe links a real blob under a temporary name and removes it again. + """ + name = "hard-link permission on blobs" + blob = self._any_blob_file() + if blob is None: + return DoctorCheck(name, True, "skipped: no blobs present") + destinations = list( + dict.fromkeys( + [ + self.config.import_staging_dir, + self.config.ollama_models_dir / ".studiolink-imports", + ] + ) + ) + outcomes: list[str] = [] + ok = True + for destination in destinations: + if not destination.is_dir(): + outcomes.append(f"{destination}: skipped (not created yet)") + continue + probe = destination / f".studiolink-probe-{os.getpid()}" + try: + probe.unlink(missing_ok=True) + os.link(blob, probe) + except OSError as exc: + ok = False + outcomes.append( + f"{destination}: FAILED ({exc}); blobs must be linkable " + "here - on Linux check blob ownership and " + "fs.protected_hardlinks, or use --copy" + ) + else: + outcomes.append(f"{destination}: ok") + finally: + try: + probe.unlink(missing_ok=True) + except OSError: + pass + return DoctorCheck(name, ok, "; ".join(outcomes)) + + def _any_blob_file(self) -> Path | None: + blobs = self.config.ollama_blobs_dir + if not blobs.is_dir(): + return None + for path in sorted(blobs.iterdir()): + if path.is_file(): + return path + return None + def _record_is_synced( self, model: OllamaModel, diff --git a/src/studiolink/state.py b/src/studiolink/state.py index 3e661f4..a928504 100644 --- a/src/studiolink/state.py +++ b/src/studiolink/state.py @@ -61,19 +61,31 @@ def _parse_record(name: str, record_data: object) -> SyncRecord | None: return None def _save_raw(self, records: Mapping[str, object]) -> None: - """Persist raw JSON dict to disk atomically.""" + """Persist raw JSON dict to disk atomically and durably.""" self.path.parent.mkdir(parents=True, exist_ok=True) payload = json.dumps({"schema_version": 2, "sync_records": records}, indent=2) - tmp_path = self.path.parent / (self.path.name + ".tmp") - tmp_path.write_text(payload, encoding="utf-8") - os.replace(tmp_path, self.path) + # A per-process temp name keeps concurrent writers from interleaving + # writes into one file, and fsync before the replace keeps a crash + # from leaving a truncated state file behind. + tmp_path = self.path.parent / f"{self.path.name}.tmp-{os.getpid()}" + try: + with open(tmp_path, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + os.replace(tmp_path, self.path) + except BaseException: + tmp_path.unlink(missing_ok=True) + raise def _load_raw(self) -> dict[str, object]: """Load raw JSON dict from disk.""" if not self.path.exists(): return {} try: - payload = json.loads(self.path.read_text(encoding="utf-8")) + # utf-8-sig tolerates editors that save the file with a BOM; + # a strict read would discard every record as "corrupted". + payload = json.loads(self.path.read_text(encoding="utf-8-sig")) except json.JSONDecodeError as exc: logger.warning( "Corrupted state file at %s: %s. Starting fresh.", self.path, exc diff --git a/src/studiolink/syncer.py b/src/studiolink/syncer.py index 03525df..6a7b4d8 100644 --- a/src/studiolink/syncer.py +++ b/src/studiolink/syncer.py @@ -37,6 +37,11 @@ def same_file(left: Path, right: Path) -> bool: left_stat, right_stat = left.stat(), right.stat() except OSError: return False + if left_stat.st_ino == 0 or right_stat.st_ino == 0: + # Filesystems without file ids (FAT/exFAT) report inode 0, which + # would make every file on the volume compare equal and reuse a + # stale alias. Identity is unknowable there, so never match. + return False return (left_stat.st_dev, left_stat.st_ino) == ( right_stat.st_dev, right_stat.st_ino, @@ -113,24 +118,30 @@ def _sync_one( message="already synced according to StudioLink state", record=existing, ) - if model.readiness is ModelReadiness.STALE: - logger.debug("Model %s has a missing artifact", model.canonical_name) - return SyncResult( - model=model, - status="error", - message=( - "model artifact is missing from the Ollama blob store; " - f"run `ollama pull {model.canonical_name}` to restore it" - ), - ) - if model.readiness is ModelReadiness.INVALID: - logger.debug("Model %s is invalid: %s", model.canonical_name, model.issues) - return SyncResult( - model=model, - status="error", - message="model is not ready for import: " - + "; ".join(model.issues or ("unknown error",)), - ) + if not already_synced: + # A complete import that Ollama can no longer back is still fine + # to keep; only a model we are about to (re-)import must be + # blocked by stale or invalid artifacts. + if model.readiness is ModelReadiness.STALE: + logger.debug("Model %s has a missing artifact", model.canonical_name) + return SyncResult( + model=model, + status="error", + message=( + "model artifact is missing from the Ollama blob store; " + f"run `ollama pull {model.canonical_name}` to restore it" + ), + ) + if model.readiness is ModelReadiness.INVALID: + logger.debug( + "Model %s is invalid: %s", model.canonical_name, model.issues + ) + return SyncResult( + model=model, + status="error", + message="model is not ready for import: " + + "; ".join(model.issues or ("unknown error",)), + ) artifacts = self._model_artifacts(model) if import_mode is ImportMode.DIRECT and len(artifacts) > 1: @@ -147,6 +158,7 @@ def _sync_one( (artifact.role, artifact.digest): artifact for artifact in (existing.artifacts if existing is not None else ()) } + destination_dir = self.config.lmstudio_models_dir / model.import_user_repo completed: list[SyncedArtifact] = [] last_result: ImportResult | None = None imported_at = ( @@ -156,13 +168,14 @@ def _sync_one( ) for artifact in artifacts: - if artifact.digest is None or artifact.blob_path is None: - return SyncResult( - model=model, - status="error", - message=f"{artifact.role.value} artifact is not importable", - ) - prior = existing_by_identity.get((artifact.role, artifact.digest)) + # A None digest can never match a stored record (records always + # carry a real digest), so the importability check below reports + # it after the reuse lookup. + prior = ( + existing_by_identity.get((artifact.role, artifact.digest)) + if artifact.digest is not None + else None + ) prior_target = prior.imported_model_path if prior is not None else None if prior is not None and prior_target is None: prior_target = ( @@ -174,6 +187,11 @@ def _sync_one( prior is not None and prior_target is not None and prior_target.is_file() + # A changed sibling digest also changes import_user_repo. + # Reusing the artifact from the old bundle directory would + # split the pair across LM Studio directories and break + # vision pairing, so re-import into the current destination. + and prior_target.parent == destination_dir ): completed.append( SyncedArtifact( @@ -187,6 +205,13 @@ def _sync_one( ) continue + if artifact.digest is None or artifact.blob_path is None: + return SyncResult( + model=model, + status="error", + message=f"{artifact.role.value} artifact is not importable", + ) + if import_mode is ImportMode.DIRECT: alias_path = artifact.blob_path alias_created = False @@ -257,7 +282,11 @@ def _sync_one( import_command=import_result.command, ) ) - if not dry_run: + if not dry_run and any( + artifact.role is ArtifactRole.MODEL for artifact in completed + ): + # Never persist a partial without the model artifact: its + # serialization requires a primary. partial = self._make_record( model, completed, link_mode, imported_at, vision_confirmed=False ) @@ -358,7 +387,9 @@ def _partial_result( dry_run: bool, ) -> SyncResult: record = None - if completed: + if completed and any( + artifact.role is ArtifactRole.MODEL for artifact in completed + ): record = self._make_record( model, completed, @@ -454,14 +485,19 @@ def _ensure_import_alias( # The alias survived a re-pull but now points at the old blob content; # replace it so we never import stale weights. logger.debug("Replacing stale import alias: %s", alias_path) - alias_path.unlink() - staging_dir.mkdir(parents=True, exist_ok=True) + try: + alias_path.unlink() + except OSError as exc: + raise RuntimeError( + f"Failed to replace stale import alias {alias_path}: {exc}" + ) from exc try: + staging_dir.mkdir(parents=True, exist_ok=True) os.link(blob_path, alias_path) - logger.debug("Created hard link: %s -> %s", alias_path, blob_path) - return alias_path, True except OSError as exc: raise RuntimeError(f"Failed to create import alias (hard link): {exc}") from exc + logger.debug("Created hard link: %s -> %s", alias_path, blob_path) + return alias_path, True def _format_import_message(result: ImportResult) -> str: diff --git a/tests/test_cli.py b/tests/test_cli.py index 02379a9..48907c2 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -249,7 +249,12 @@ def test_multi_digit_patch_compares_numerically(self): assert cli._version_tuple("1.0.0") > cli._version_tuple("0.99.99") def test_versions_with_suffixes_do_not_crash(self): - assert cli._version_tuple("0.1.0rc1") == (0, 1, 1) + # Regression: "1rc1" used to concatenate its digits into 11, so a + # pre-release compared as newer than any 0.1.x release. Suffixes are + # now truncated, so a pre-release never looks newer than its release. + assert cli._version_tuple("0.1.0rc1") == (0, 1, 0) + assert not cli._version_tuple("0.1.0rc1") > cli._version_tuple("0.1.0") + assert cli._version_tuple("0.1.1") > cli._version_tuple("0.1.0rc1") class TestUpgradeCommand: diff --git a/tests/test_service.py b/tests/test_service.py index c4b02ef..b058ae0 100644 --- a/tests/test_service.py +++ b/tests/test_service.py @@ -12,6 +12,7 @@ ) import studiolink.service as service_module +from studiolink.lmstudio_adapter import LMStudioError from studiolink.models import LinkMode from studiolink.ollama_adapter import OllamaAdapter from studiolink.service import StudioLinkService @@ -501,3 +502,154 @@ def test_select_models_matches_repository_all_tags( selected = service._select_models(models, ["llama3"]) assert {m.tag for m in selected} == {"1b", "70b"} + + +class TestStatusInventoryDegradation: + def make_synced_vision_model(self, config, service): + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = OllamaAdapter(config).scan_models()[0] + result = service.sync(model_names=[model.canonical_name])[0] + assert result.status == "synced" + return model + + def test_status_survives_lm_studio_inventory_failure( + self, make_config, fake_lmstudio, monkeypatch + ): + # Regression: a broken lms used to crash the whole status command for + # users with synced vision models. + config = make_config() + fake_lmstudio.models_dir = config.lmstudio_models_dir + service = build_service(config, fake_lmstudio) + self.make_synced_vision_model(config, service) + + def broken_inventory(): + raise LMStudioError("lms is broken", ["lms"], 1, "boom") + + monkeypatch.setattr(fake_lmstudio, "list_models", broken_inventory) + + entries = service.status() + + entry = next(e for e in entries if e.model.canonical_name == "llava:1b") + assert entry.synced is False + assert entry.display_status == "pending" + + def test_status_uses_inventory_when_available(self, make_config, fake_lmstudio): + config = make_config() + fake_lmstudio.models_dir = config.lmstudio_models_dir + service = build_service(config, fake_lmstudio) + self.make_synced_vision_model(config, service) + + entries = service.status() + + entry = next(e for e in entries if e.model.canonical_name == "llava:1b") + assert entry.synced is True + + +class TestDoctorHardLinkPermission: + def test_probe_passes_on_linkable_filesystem(self, make_config, fake_lmstudio): + config = make_config() + write_manifest(config, digest=DIGEST_A) + write_blob(config, DIGEST_A) + config.import_staging_dir.mkdir(parents=True) + service = build_service(config, fake_lmstudio) + + checks = service.doctor() + + check = next(c for c in checks if c.name == "hard-link permission on blobs") + assert check.ok is True + assert "ok" in check.details + assert not any( + probe.name.startswith(".studiolink-probe-") + for probe in config.import_staging_dir.iterdir() + ) + + def test_probe_reports_unlinkable_blobs( + self, make_config, fake_lmstudio, monkeypatch + ): + config = make_config() + write_manifest(config, digest=DIGEST_A) + write_blob(config, DIGEST_A) + config.import_staging_dir.mkdir(parents=True) + service = build_service(config, fake_lmstudio) + + def denied(source, target, *args, **kwargs): + raise PermissionError(1, "Operation not permitted") + + monkeypatch.setattr(service_module.os, "link", denied) + + checks = service.doctor() + + check = next(c for c in checks if c.name == "hard-link permission on blobs") + assert check.ok is False + assert "FAILED" in check.details + assert "fs.protected_hardlinks" in check.details + + def test_probe_skips_without_blobs(self, make_config, fake_lmstudio): + config = make_config() + for directory in ( + config.ollama_manifests_dir, + config.ollama_blobs_dir, + config.lmstudio_models_dir, + ): + directory.mkdir(parents=True) + service = build_service(config, fake_lmstudio) + + checks = service.doctor() + + check = next(c for c in checks if c.name == "hard-link permission on blobs") + assert check.ok is True + assert "skipped" in check.details + + def test_doctor_checks_lm_studio_inventory(self, make_config, fake_lmstudio): + config = make_config() + config.ollama_manifests_dir.mkdir(parents=True) + config.ollama_blobs_dir.mkdir(parents=True) + config.lmstudio_models_dir.mkdir(parents=True) + service = build_service(config, fake_lmstudio) + + checks = service.doctor() + + check = next(c for c in checks if c.name == "lm studio model inventory") + assert check.ok is True + assert "indexed" in check.details + + +class TestPruneSweepsCopyStaging: + def test_sweeps_copy_staging_leftovers(self, make_config, fake_lmstudio): + # Copy-mode aliases are removed after each import; anything found in + # .studiolink-imports survived a crash and pins blob space. + config = make_config() + service = build_service(config, fake_lmstudio) + write_manifest(config, digest=DIGEST_A) + blob = write_blob(config, DIGEST_A) + model = OllamaAdapter(config).scan_models()[0] + copy_staging = config.ollama_models_dir / ".studiolink-imports" + copy_staging.mkdir(parents=True) + leftover = copy_staging / "crashed-leftover.gguf" + leftover.write_bytes(b"GGUFxxxx") + healthy = copy_staging / model.import_filename + os.link(blob, healthy) + + report = service.prune() + + removed = {result.path for result in report.aliases if result.removed} + assert leftover in removed + assert healthy.exists() diff --git a/tests/test_state.py b/tests/test_state.py index 826d7db..bb27e58 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -157,3 +157,31 @@ def test_record_serializes_link_mode(self, tmp_path): def test_record_from_json_requires_fields(self): with pytest.raises(KeyError): SyncRecord.from_json({"canonical_name": "m:1"}) + + +class TestStateDurability: + def test_loads_state_saved_with_utf8_bom(self, tmp_path): + # Regression: an editor that saves state.json with a BOM used to make + # every record disappear ("Starting fresh") and re-import everything. + path = tmp_path / "state.json" + record = make_sync_record("llama3:1b", DIGEST_A) + StateStore(path).upsert(record) + raw = path.read_bytes() + assert not raw.startswith(b"\xef\xbb\xbf") + path.write_bytes(b"\xef\xbb\xbf" + raw) + + restored = StateStore(path).get_record("llama3:1b") + + assert restored is not None + assert restored.canonical_name == "llama3:1b" + assert restored.digest == DIGEST_A + + def test_save_leaves_no_temp_files_behind(self, tmp_path): + path = tmp_path / "state.json" + store = StateStore(path) + + store.upsert(make_sync_record("llama3:1b", DIGEST_A)) + store.upsert(make_sync_record("llama3:2b", DIGEST_A)) + + assert [item.name for item in path.parent.iterdir()] == [path.name] + assert len(store.get_all_records()) == 2 diff --git a/tests/test_syncer.py b/tests/test_syncer.py index 22d7cd8..5398e6b 100644 --- a/tests/test_syncer.py +++ b/tests/test_syncer.py @@ -1,9 +1,12 @@ import errno import os +import types +from pathlib import Path from conftest import ( DIGEST_A, DIGEST_B, + blob_filename, make_ollama_model, write_blob, write_manifest, @@ -588,3 +591,214 @@ def test_sync_result_carries_model(self, make_syncer): results = syncer.sync([model], **sync_kwargs()) assert results[0].model is model assert results[0].model.readiness is ModelReadiness.READY + + +class TestAliasFilesystemErrors: + def test_blocked_staging_dir_is_per_model_error(self, make_syncer): + # Regression: PermissionError/FileExistsError from mkdir() or the + # stale-alias unlink() escaped _sync_one and aborted the whole batch. + syncer, config, fake = make_syncer() + write_manifest(config, repository="m1", tag="1b", digest=DIGEST_A) + write_manifest(config, repository="m2", tag="1b", digest=DIGEST_B) + write_blob(config, DIGEST_A) + write_blob(config, DIGEST_B) + config.import_staging_dir.parent.mkdir(parents=True, exist_ok=True) + config.import_staging_dir.write_text("a file, not a directory") + + results = syncer.sync(scan_models(config), **sync_kwargs()) + + assert [result.status for result in results] == ["error", "error"] + assert all("import alias" in result.message for result in results) + assert fake.calls == [] + + def test_stale_alias_unlink_failure_is_per_model_error( + self, make_syncer, monkeypatch + ): + syncer, config, fake = make_syncer() + write_manifest(config, digest=DIGEST_A) + write_blob(config, DIGEST_A) + model = scan_models(config)[0] + config.import_staging_dir.mkdir(parents=True) + stale = config.import_staging_dir / model.import_filename + stale.write_bytes(b"stale content") + + def denied(path, *args, **kwargs): + if path == stale: + raise PermissionError(1, "Operation not permitted") + return real_unlink(path, *args, **kwargs) + + real_unlink = Path.unlink + monkeypatch.setattr(Path, "unlink", denied) + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "error" + assert "stale import alias" in result.message + + def test_zero_inode_files_never_compare_equal(self, tmp_path, monkeypatch): + # Filesystems without file ids (FAT/exFAT) report st_ino == 0 for + # every file; identity must be treated as unknowable rather than + # matching every file on the volume (stale-weight reuse risk). + left = tmp_path / "a.gguf" + right = tmp_path / "b.gguf" + left.write_bytes(b"GGUFsame-size") + right.write_bytes(b"GGUFsame-size") + real_stat = os.stat + + def inodeless_stat(path, *args, **kwargs): + st = real_stat(path, *args, **kwargs) + return types.SimpleNamespace( + st_dev=st.st_dev, + st_ino=0, + st_size=st.st_size, + st_mtime_ns=st.st_mtime_ns, + ) + + monkeypatch.setattr(Path, "stat", inodeless_stat) + + assert same_file(left, right) is False + assert same_file(left, left) is False + + +def write_bundle(config, model_digest, projector_digest, *, model_first): + layers = [ + {"mediaType": "application/vnd.ollama.image.model", "digest": model_digest}, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + if not model_first: + layers.reverse() + write_manifest(config, repository="llava", content={"layers": layers}) + + +class TestProjectorFirstManifests: + def test_projector_first_manifest_imports_model_first(self, make_syncer): + # Regression: a partial record persisted before the model artifact + # made primary_artifact raise StopIteration and abort the batch. + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_bundle(config, DIGEST_A, projector_digest, model_first=False) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "synced" + assert [artifact["user_repo"] for artifact in fake.calls] == [ + model.import_user_repo + ] * 2 + assert fake.calls[0]["source_path"].endswith(model.import_filename) + record = StateStore(config.state_file).get_record(model.canonical_name) + assert record is not None + assert [artifact.role for artifact in record.artifacts] == [ + ArtifactRole.MODEL, + ArtifactRole.PROJECTOR, + ] + + def test_failed_model_import_in_projector_first_batch_continues(self, make_syncer): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_bundle(config, DIGEST_A, projector_digest, model_first=False) + write_manifest(config, repository="mistral", tag="7b", digest=DIGEST_B) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + write_blob(config, DIGEST_B) + models = {m.canonical_name: m for m in scan_models(config)} + fake.fail_for = { + str(config.import_staging_dir / models["llava:1b"].import_filename) + } + + results = syncer.sync( + [models["llava:1b"], models["mistral:7b"]], **sync_kwargs() + ) + + assert results[0].status == "error" + assert results[0].record is None # no projector-only partial persisted + assert results[1].status == "synced" + records = StateStore(config.state_file).get_all_records() + assert set(records) == {"mistral:7b"} + + +class TestBundleCoLocation: + """A changed sibling digest changes import_user_repo; both artifacts must + end up in the new bundle directory or LM Studio cannot pair them.""" + + def test_changed_model_digest_reimports_whole_bundle(self, make_syncer): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_bundle(config, DIGEST_A, projector_digest, model_first=True) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + assert syncer.sync([model], **sync_kwargs())[0].status == "synced" + + write_blob(config, DIGEST_B) + write_bundle(config, DIGEST_B, projector_digest, model_first=True) + model = scan_models(config)[0] + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "synced" + new_repo = model.import_user_repo + assert [call["user_repo"] for call in fake.calls[2:]] == [new_repo, new_repo] + record = StateStore(config.state_file).get_record("llava:1b") + assert record is not None + assert all( + artifact.imported_model_path is not None + and artifact.imported_model_path.parent + == config.lmstudio_models_dir / new_repo + for artifact in record.artifacts + ) + + def test_changed_projector_digest_reimports_whole_bundle(self, make_syncer): + # The dangerous direction: the unchanged model must move to the new + # bundle directory too, and vision must be confirmed against it. + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_bundle(config, DIGEST_A, projector_digest, model_first=True) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + assert syncer.sync([model], **sync_kwargs())[0].status == "synced" + + new_projector = "sha256:" + "d" * 64 + write_blob(config, new_projector) + write_bundle(config, DIGEST_A, new_projector, model_first=True) + model = scan_models(config)[0] + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "synced" + new_repo = model.import_user_repo + assert [call["user_repo"] for call in fake.calls[2:]] == [new_repo, new_repo] + assert fake.calls[3]["source_path"].endswith( + model.artifact_import_filename(model.artifacts[1]) + ) + record = StateStore(config.state_file).get_record("llava:1b") + assert record is not None + assert all( + artifact.imported_model_path is not None + and artifact.imported_model_path.parent + == config.lmstudio_models_dir / new_repo + for artifact in record.artifacts + ) + + def test_synced_bundle_skips_when_blob_is_removed(self, make_syncer): + # An intact LM Studio import needs nothing from Ollama; "already + # synced" must win over the stale check for bundles too. + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_bundle(config, DIGEST_A, projector_digest, model_first=True) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + assert syncer.sync([model], **sync_kwargs())[0].status == "synced" + (config.ollama_blobs_dir / blob_filename(projector_digest)).unlink() + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "skipped" + assert len(fake.calls) == 2