Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
198 changes: 198 additions & 0 deletions docs/research/branch-reliability-audit.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion src/studiolink/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

__all__ = ["__version__"]

__version__ = "0.3.0"
__version__ = "0.3.1"
11 changes: 8 additions & 3 deletions src/studiolink/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import argparse
import json
import logging
import re
import subprocess
import sys
import urllib.request
Expand Down Expand Up @@ -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",
]
Expand Down Expand Up @@ -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)


Expand Down
9 changes: 5 additions & 4 deletions src/studiolink/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions src/studiolink/ollama_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
100 changes: 96 additions & 4 deletions src/studiolink/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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,
Expand Down
22 changes: 17 additions & 5 deletions src/studiolink/state.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading