3lc-compute-plugin-sdk 0.3.0__tar.gz → 0.3.2__tar.gz

{3lc_compute_plugin_sdk-0.3.0 → 3lc_compute_plugin_sdk-0.3.2}/.github/workflows/docs.yml

@@ -1,10 +1,11 @@
 name: docs
 
 # Build the Sphinx docs and publish to GitHub Pages.
-# Manual-only by choice: run from the Actions tab (or `gh workflow run docs`)
-# when the docs should go out — pushes to main do NOT redeploy.
-# One-time setup: repo Settings -> Pages -> Source = "GitHub Actions".
+# Deploys automatically on every release tag, or manually from the Actions tab
+# (`gh workflow run docs`). One-time setup: repo Settings -> Pages -> Source = "GitHub Actions".
 on:
+  push:
+    tags: ["v*"]
   workflow_dispatch:
 
 # Least-privilege token for the Pages deploy.

3lc_compute_plugin_sdk-0.3.2/1.0-READINESS.md

@@ -0,0 +1,434 @@
+# 1.0 readiness report — 3lc-compute-plugin-sdk
+
+*Audit of SDK `main` @ `576bcd5` (0.2.0, includes JS_CONTRACT 0.2 / PR #8), host `3lc-compute` @ `bbf2aed`,
+Hub frontend, and all 9 first-party plugins (exporter, importer, merger, splitter, image-metrics,
+table-statistics, timm, sam3, yolo). Line numbers reference those revisions. Uncommitted working doc.*
+
+**Framing** (per the pre-1.0 window): all consumers are in-house, so breaking is cheap *now* —
+grep-and-fix across our own repos, coordinated via editable overlays and the frontend contract test.
+Every breaking proposal below states who migrates and roughly how.
+
+---
+
+## The shape of the problem (executive summary)
+
+1. **The contract that's written down is healthy; the contract that's *lived* is bigger and undeclared.**
+   The `PluginApi` top level matches the d.ts exactly (the conformance test passes), but the surface
+   plugins actually depend on includes `openTablePicker` (7 of 8 UI plugins), 13 SDK-injected `_tlc*`
+   globals (6 of 8 plugins), `CancelJob`, bare `showToast`, `cssVar`, `plugin-common.css` classes, and
+   an `allowErrorStatus` fetch option the host itself uses 13×. None of that is in the d.ts. 1.0 should
+   be the moment the declared contract and the lived contract become the same thing.
+2. **The job-reporting API is fought by its heaviest users.** `ctx.result(run_url=)` is called by only
+   2 of 7 job plugins — all three GPU trainers smuggle their result URL through `ctx.emit`/`ctx.metric`
+   instead; failure reporting is hand-rolled (`ctx.emit("job_failed", ...)` + `raise`) in duplicate;
+   the failure message rides `PluginJobUpdate.subtitle`. These are the exact warts that freeze at 1.0.
+3. **The version story has three axes and one consumer.** `PY_CONTRACT`/`JS_CONTRACT` are read by
+   nobody (host compares `sdk_version` only; zero plugin references); the manifest `sdk_version` the
+   SDK docstring promises is read by nobody; and `PLUGIN_API.contractVersion` is `''` in every
+   production frontend container. Consolidate to one axis and make it actually reach production.
+4. **Live pin defect, before anything else:** the host and the plugins umbrella pin
+   `3lc-compute-plugin-sdk[shared]>=0.1.0,<0.2.0` — which *excludes the current 0.2.0 release* — so
+   three shipped 0.2 features (host-mode GPU reclaim, `/reclaim`, `/health` skew detection) are inert
+   in the resolved lock (host `pyproject.toml:24`, acknowledged at `job_manager.py:59-71`).
+5. **Ceremony is measurable.** 8/9 plugins repeat the same `_ui_cache` + `Path(__file__)` +
+   `read_text` block; 5/9 implement `compute()` as a dead stub; script injection exists in **four**
+   idioms (two of them the exact footgun `ui_inject.py` was written to eliminate, one injection dead
+   on both ends); the config-CRUD route quartet is copy-pasted 4×; yolo reimplements
+   `PluginConfigStore` wholesale.
+
+---
+
+## A. Break at 1.0 (ranked by leverage)
+
+### A1. Reshape job *reporting*: `result`, failure, and the error field
+
+- **What/where:** `src/tlc_plugin_sdk/job_context.py:75-87` (`result(*, run_url)`),
+  `contract/plugin-api.d.ts` `PluginJobUpdate` (failure message documented as riding `subtitle`),
+  host translation `3lc-compute/src/tlc_compute/plugins/job_manager.py:461-479`.
+- **Why it hurts:** the name `run_url` is wrong for half the producers (importers/exporters/mergers
+  produce *tables*), and the evidence says the API lost its users: only merger (`__init__.py:147`) and
+  importer (`:1553`) call `ctx.result`; timm ships the URL via `ctx.emit("job_completed", {..., "run_url"})`
+  (`timm/__init__.py:258-261`), yolo likewise (`:299-308`), and sam3 abuses `ctx.metric("run", str(run.url))`
+  (`:393-394`) — so the generic panel's "open result" link works for 2 of 7 job plugins. Failure has no
+  first-class API at all: timm `:266-269` and yolo `:311-313` both hand-emit `job_failed` + `raise`, and
+  the frontend reads the failure message out of `subtitle`. All of this freezes at 1.0 if untouched.
+- **Proposed 1.0 shape:**
+  - `ctx.result(url: str, *, kind: str = "run")` (or just `url=`); keep emitting `run_url` on the wire
+    *or* rename the wire field to `result_url` in the same coordinated set.
+  - Add `error` to the generic job record/`PluginJobUpdate` (host sets it from the terminal `error`
+    event); keep `subtitle` as display text. Optionally add `ctx.fail(message)` sugar (equivalent to
+    raising, for validation paths) — that part is additive.
+  - Document `percent=-1` (indeterminate) in `JobContext.progress` itself — today it's only in the
+    guide (`docs/plugin-guide.md:530`), and importer relies on it (`:1578,1621`).
+- **Additive or breaking:** breaking (kwarg rename + wire-field addition/rename).
+- **Who migrates:** SDK (`job_context.py`, d.ts `PluginJobUpdate`); host (`job_manager.py:473-474`,
+  `_Job.to_generic` `:109-122`); frontend (queue-panel/cancel-job read of `run_url`/`subtitle`);
+  plugins: merger + importer one line each, then timm/yolo/sam3 *adopt* `ctx.result` and delete their
+  workarounds (a net simplification, not just a rename).
+- **Effort:** M.
+
+### A2. Collapse the three version axes to one, and make it reach production
+
+- **What/where:** `src/tlc_plugin_sdk/__init__.py:39-56` (`PY_CONTRACT`, `JS_CONTRACT`),
+  `asgi_app.py:52-59` (`/health` reports all three), frontend `app.py:22-28` + `pyproject.toml:17-34`.
+- **Why it hurts:** `PY_CONTRACT`/`JS_CONTRACT` have **zero consumers** — the host's skew check
+  compares only `sdk_version` (`3lc-compute/plugins/versioning.py:128-164`), no plugin reads them, and
+  the frontend's use of `JS_CONTRACT` is broken in production: the SDK is a dev-group-only dependency
+  (`frontend/pyproject.toml:33`), the Docker image installs only `[project.dependencies]`, so
+  **`PLUGIN_API.contractVersion === ''` in every shipped container** and all documented 0.2
+  feature-detection (`location`, `resolveLocation?`, `getLocations?`) reports "pre-0.1 host". Three
+  axes is bookkeeping we pay on every release for a distinction nothing exercises. Also: the SDK
+  docstring's claim that plugins declare `sdk_version` in their manifest (`__init__.py:32-33`) is
+  fiction — no manifest has it, no host code reads it.
+- **Proposed 1.0 shape:** `SDK_CONTRACT_VERSION` is the one version. Delete `PY_CONTRACT`/`JS_CONTRACT`
+  exports; the d.ts header states the package version it shipped in. `/health` reports `sdk_version`
+  only. The frontend derives `contractVersion` from the *compute service* (it already calls
+  `GET /api/plugins/` and `/health`) instead of a locally-installed Python package — that fixes the
+  production hole structurally rather than by promoting the SDK to a frontend runtime dep. Fix or
+  delete the `sdk_version`-manifest docstring claim (see A6).
+- **Additive or breaking:** breaking (removes two public constants and two `/health` fields).
+- **Who migrates:** SDK (`__init__.py`, `asgi_app.py`, d.ts header, guide's "Two version axes"
+  section); frontend (`app.py`, `base.html:48`, `plugin-loader.js:210` → read from compute);
+  host: nothing (never consumed them). Plugins: nothing.
+- **Effort:** M (the frontend sourcing change is the real work).
+
+### A3. Bring the escaped browser surface into the contract; kill the bare globals
+
+- **What/where:** frontend `static/js/table-picker.js:62` (`openTablePicker`, used by **7 of 8** UI
+  plugins), `cancel-job.js:29` (`CancelJob`, yolo+timm), `main.js:202/170` (bare `showToast`, `cssVar`);
+  SDK-injected `_tlc*` globals — 13 functions across `shared/alias_ui.py`, `alias_override_ui.py`,
+  `config_ui.py`, used by 6 of 8 plugins, none declared in the d.ts.
+- **Why it hurts:** this is contract-shaped surface with no contract: no d.ts entry, no conformance
+  gate, no stability tier. `openTablePicker(targetInputId)` additionally couples via a global DOM id
+  (`table-picker.js:308` reaches out of the plugin container), and the host fires both `input` *and*
+  `change` events because five named plugins disagree on which to listen for (`table-picker.js:308-317`).
+  The underscore prefix on `_tlc*` says "private" while the usage pattern is "public API".
+- **Proposed 1.0 shape:**
+  - `PLUGIN_API.pickers.table(options) → Promise<string|null>` (promise-returning, no DOM-id
+    coupling; frontend wraps the existing picker). There is no run picker today — declare only what
+    exists, add `pickers.run` later additively.
+  - `PLUGIN_API.jobs.cancelDialog(jobId, opts)` or declare `CancelJob` as-is in the d.ts; plugins
+    already use `PLUGIN_API.showToast`, so delete the bare-global usage (importer ×3).
+  - Rename the injected `_tlc*` families under one declared namespace (e.g. `window.TlcPluginUi.alias.*`,
+    `.aliasOverride.*`, `.configBar(...)`) with d.ts declarations; ship thin deprecated aliases during
+    the migration window, drop the bare `_tlc*` names at 1.0.
+- **Additive or breaking:** additive to introduce, breaking to remove the old globals at 1.0 (that
+  removal is the point — otherwise the undeclared surface stays load-bearing forever).
+- **Who migrates:** frontend (implement `pickers`, declare members, then delete the legacy event
+  double-fire once all plugins use the promise API); SDK (rename injected JS + d.ts declarations);
+  plugins: mechanical sweep — `openTablePicker` call sites in 7 plugins, `_tlc*` call sites in 5.
+- **Effort:** M–L (mechanical but wide; the contract-test extension in C3 keeps it honest).
+
+### A4. Make the SDK own the manifest schema — and fix the doc/code lies about it
+
+- **What/where:** manifest parsing lives host-side (`3lc-compute/plugins/manifest.py:140-248`) with
+  no schema, while the SDK documents it (`docs/plugin-guide.md:104-157`). Confirmed divergences:
+  - `isolation` default: guide says `venv` is the default (`plugin-guide.md:130`); host code defaults
+    to **`host`** (`registry.py:392`) — the opposite, and the dangerous direction (in-process import).
+  - `socketio_namespace`: guide says declare-to-override (`:134-137`); host **hardcodes** `f"/{pid}"`
+    and never reads the key (`manifest.py:219-221`).
+  - `provision_extra`: guide says REQUIRED for venv (`:133,140`); host treats it as optional and
+    silently falls back to in-place resolution (`worker_spec.py:351-397`).
+  - Undocumented keys the host reads: `runtime.auth_exempt_paths`, `runtime.venv_python`,
+    `runtime.python`, `runtime.training`, `ui.min_input_count`, `ui.action_param_names`,
+    `ui.quick_action_label/description` (`manifest.py:191-216`).
+  - Documented keys nothing reads: `sdk_version`, `ui.fragment`, `display_mode = "hidden"` (no host
+    branch on it).
+  - No `max_input_count`: image-metrics encodes "1–10 tables" as `input_types = ["table"] × 10`
+    (`tlc_plugin_image_metrics/plugin.toml:13`).
+  - No reserved-id list: `id = "jobs"` (or `manifest`, `by-resource`, `install`, …) passes the id
+    pattern (`identity.py:52`) and is then unroutable under `/api/plugins`.
+  - A TOML parse error makes the plugin **vanish silently** (`manifest.py:115-121`) — contradicting
+    the stated design goal of "listed greyed-out, never vanishing".
+  - `contract.py:8-9` says the manifest is "`[tool.tlc-compute]` in plugin.toml" — all 9 real
+    manifests are bare top-level `plugin.toml`; the `[tool.tlc-compute]` form only applies to
+    `pyproject.toml`.
+- **Why it hurts:** the manifest *is* contract surface — every key an author writes is a promise —
+  and right now the source of truth is a host file the SDK repo can't see, with drift in both
+  directions and no validation (string `priority` takes down `GET /api/plugins` wholesale,
+  `registry.py:725`).
+- **Proposed 1.0 shape:** a typed `tlc_plugin_sdk.manifest` module (dataclass + `parse()` +
+  validation errors) that the **host imports** — SDK is already the root of the dependency graph, so
+  this is the natural home. In the same move: require `isolation` explicitly (all 9 manifests already
+  declare it — zero real migration); either implement `socketio_namespace` override or delete it from
+  the schema/docs (recommend delete — nothing has ever overridden it); make `provision_extra`
+  actually required for venv (validation error); add `max_input_count`; reserve the literal path
+  segments (`jobs`, `manifest`, `by-resource`, `venv`, …) in id validation; document the rest.
+  Also add `/venv` to the reserved-route list in `contract.py:105` (host owns
+  `GET /api/plugins/{id}/venv`; a plugin's `@get("/venv")` is silently shadowed today).
+- **Additive or breaking:** breaking (required `isolation`, dropped dead keys, host adopts SDK parser).
+- **Who migrates:** host (manifest.py becomes a consumer of the SDK schema — the big piece);
+  plugins: none in practice; docs: guide's manifest section becomes generated-from/checked-against
+  the schema.
+- **Effort:** L (mostly host-side; the SDK module itself is S–M).
+
+### A5. Prune and re-tier `shared.*` (the graduation question)
+
+- **What/where & evidence (usage census across all 9 plugins + host):**
+  - `shared/modality.py` (551 lines — the largest shared module): plugins use exactly **one** of its
+    five public functions (`detect_modality_from_table`, 5 plugins). `detect_modality_from_url` has
+    **zero references anywhere**; `detect_modality_from_schema` and `classify_metrics_columns` are
+    internal/host-only. It is 551 lines of heuristics (7-step fallback chains, name conventions)
+    published as forever-contract.
+  - `shared/labels.py`: three plugins use one distinct function each, no overlap;
+    `candidate_label_paths`/`find_label_path`/`get_label_map` have no external callers.
+  - `shared/generic_job.epoch_progress`: 2 users (timm, yolo) — and **both** also maintain a private
+    `_timing` dict + hand-rolled elapsed/avg/ETA computation + a local `avg_epoch_s → avg_step_s`
+    remap (`yolo/__init__.py:184-191`, `timm/__init__.py:144-154`) because the helper only formats,
+    it doesn't *track*. The abstraction is at the wrong altitude.
+  - `shared/url_utils.normalize_url`: adoption ~25% (29 bypassing `tlc.Table.from_url` calls vs ~9
+    using it), and its heuristics are platform folklore — `url.startswith(("Users/", "home/"))`
+    re-adds a lost leading slash (`url_utils.py:37-39`), macOS/Linux-specific, silently wrong
+    elsewhere.
+  - `shared/model_storage.py`: 2 users (timm, yolo); `on_status: Any` where it means
+    `Callable[[str], None]`; contains an `except AttributeError` probe for a `tlc.Url` method.
+  - `shared/config_store.py`: healthy (3 users + yolo's clone proves demand) but leans on
+    `# type: ignore[attr-defined]` ×5 for the id/created/last_run envelope — the repo's own
+    CLAUDE.md bans that.
+- **Proposed 1.0 shape:**
+  - **Graduate (stable core):** `ui_inject`, `job_tracker`, `config_store` (with a typed envelope —
+    a `PluginConfigBase` dataclass or Protocol killing the `type: ignore`s), `aliases`, `images`,
+    `labels` (public trio only), `naming`.
+  - **Trim:** delete `detect_modality_from_url` (zero users); underscore
+    `detect_modality_from_schema`, `candidate_label_paths`, `find_label_path` (internal helpers).
+  - **Mark experimental:** `modality` detection heuristics — either a `shared.experimental` namespace
+    or an explicit "best-effort, may change in minors" tier in the docstring + docs, mirroring the
+    `libs` tier precedent. Freezing 551 lines of heuristics at 1.0 is the single biggest frozen-wart
+    risk in the package.
+  - **Replace:** `epoch_progress` with an `EpochTimer` that owns the timing dict + ETA math both
+    trainers reimplement (additive add, breaking delete of `epoch_progress` — 2 trivial migrations).
+    `normalize_url` → either push proper resolution into `tlc` core or reduce it to the defensible
+    subset (absolute-ize + project-root resolution) and delete the "Users/" folklore.
+  - **Tighten:** `model_storage` signatures (`on_status: Callable[[str], None] | None`).
+  - **The `[shared]` extra:** keep the split. The pyproject "direction" note (`pyproject.toml:43`)
+    says `3lc` likely returns to base — but the frontend is a real bare-SDK consumer (it installs the
+    SDK purely for the d.ts). Recommend deleting that direction note and declaring the split
+    permanent at 1.0.
+- **Additive or breaking:** mixed; the deletions/underscorings are breaking.
+- **Who migrates:** essentially nobody for the deletions (zero external users, verified); timm+yolo
+  for `epoch_progress`; call-site sweep for `normalize_url` semantics (5 plugins, host insights
+  plugins).
+- **Effort:** M.
+
+### A6. Fix `contractVersion`'s meaning and the d.ts's own identity strings
+
+- **What/where:** the d.ts references the **pre-rename distribution name** `3lc-plugin-sdk` in three
+  places (`plugin-api.d.ts:26, 353, 416`); the guide (`plugin-guide.md:313`) and `docs/api.md:32` say
+  `/// <reference types="3lc-compute-plugin-sdk/contract/plugin-api" />` while the d.ts header
+  (`:24-27`) explains at length why it must be the *import* name `tlc_plugin_sdk`. The guide's
+  version table (`plugin-guide.md:785-787`) still says JS_CONTRACT 0.1 / package 0.1.0. README says
+  "0.1 is the released contract line" and that the base deps include `3lc` (`README.md:46,52`) —
+  both wrong.
+- **Why it hurts:** the contract document contradicting itself about its own name and version is
+  exactly the kind of thing a first external plugin author trips on day one.
+- **Proposed 1.0 shape:** one pass fixing every self-reference; if A2 lands, the "Two version axes"
+  section collapses to one paragraph. Decide the `<reference>` path question once (test both forms in
+  an editor, document the winner, delete the loser).
+- **Additive or breaking:** docs-only (bundled here because it must land *with* A2's reshape).
+- **Effort:** S.
+
+---
+
+## B. Additive anytime (ranked)
+
+### B1. Auto-inject the SDK client scripts at serve time (kill the injection ceremony)
+
+- **What/where:** every job-using plugin must remember
+  `inject_scripts(raw, job_tracker_script())`. Reality check across 9 plugins: **four different
+  idioms** — `inject_scripts` (4 plugins); the literal `raw.replace("<script>", ...)` footgun that
+  `ui_inject.py:16-22` was written to eliminate (sam3 `__init__.py:50-55`); a brittle 3-line-exact
+  source-string match (importer `:1691-1694`); wholesale script-block prepending (merger `:104`,
+  splitter `:157`). Plus one **dead** injection: exporter injects `alias_override_ui_script()` into a
+  `ui.html` that never references any alias function (`exporter/__init__.py:381-386`).
+- **Proposal:** `build_plugin_app`'s `/ui` handler (`asgi_app.py:64-66`) — and the host's in-process
+  ui path — injects `JOB_TRACKER_JS` automatically. The client is already idempotent
+  (`if (window.PluginJobs) return;`, `job_tracker.py:33`), so existing plugins keep working and can
+  delete their injection lines at leisure. Alias/config UI injection becomes a manifest opt-in
+  (`[ui] inject = ["alias", "alias_override", "config_bar"]`) or stays manual — either way documented.
+- **Effort:** S–M. Migration: none required; cleanup sweep optional.
+
+### B2. De-abstract `compute()`
+
+- **What/where:** `contract.py:56-59` makes `compute()` abstract; 5 of 9 plugins implement it as a
+  dead stub (timm `:56` returns `{"status": "Use /api/plugins/timm/* endpoints"}`, etc.). The
+  `/compute` route also injects a magic `params.setdefault("url", "")` (`asgi_app.py:71`).
+- **Proposal:** give it a default returning `{"error": "<id> does not implement compute()"}` —
+  mirroring `run_job`'s default — so `get_ui_fragment` is the only abstract. Drop the magic `url`
+  defaulting (let plugins read their own params). Deleting five stubs is optional cleanup.
+- **Effort:** S. (The `url` defaulting change is technically behavior-breaking for any plugin relying
+  on the key existing — grep says none do.)
+
+### B3. Ship the missing batteries the plugins keep hand-rolling
+
+Evidence-ranked by duplication count:
+
+| Gap | Duplication evidence | Proposal |
+|---|---|---|
+| HTML-escape helper in JS | identical `_esc` in **8/8** ui.html files | ship in the injected client (`TlcPluginUi.esc`) and declare it |
+| Plugin-scoped fetch | 8/8 re-derive `getConfig('compute_service_url') + '/api/plugins/<id>/...'`; timm/yolo/sam3/image-metrics each wrap it 2–3× with per-plugin timeouts; sam3 hardcodes a `localhost:5020` fallback (`sam3/ui.html:296`) | `PLUGIN_API.pluginFetch(path, opts)` — pre-scoped to the mounted plugin's route root, with a venv-aware default timeout (timm's comment at `ui.html:474-477` documents why 10s is wrong for cold-start workers) |
+| Config CRUD routes | the same `GET/POST /configs`, `GET /configs/{id}`, `POST /configs/{id}/delete` quartet 4× (image_metrics, timm, sam3, yolo), with **three different** dataclass↔dict marshalling answers | `shared.config_routes.make_config_routes(store) -> list[BaseRouteHandler]` — pairs with the graduated `config_store`; also removes yolo's incentive to keep its `ProjectStore` clone (97 lines) |
+| Alias-override lifecycle | identical `apply_alias_overrides → try → finally: restore_aliases` 4×, with **three different** param keys (`_alias_overrides` popped / gotten, `alias_overrides`) | `with alias_overrides(params) as ...:` context manager + one blessed param key |
+| Duration/ETA/log-pane UI | duration formatter 4×, timing-strip renderer 3×, log-pane appender 4×, config-picker-with-localStorage ~100 lines × 3 (only image_metrics uses `_tlcPluginConfig`) | fold into the declared injected client (per A3's namespace) |
+| Table identity | `getattr(table, "project_name", "") or ""` ×6 across timm/yolo/image_metrics | tiny `shared.tables.table_identity(table)` helper (or a `tlc` core ask) |
+| Task detection | `timm/task_detection.py` ≈ `yolo/task_detection.py` (same 60 lines, different tail) | `shared.modality.detect_task(table, mapping)` |
+
+- **Effort:** M total; each row is S. All additive.
+
+### B4. `PluginJobs` v2 — close the gap that makes GPU plugins hand-roll sockets
+
+- **What/where:** all four plugins that need custom events (`timm`, `yolo`, `sam3`, `image_metrics`)
+  bypass `PluginJobs` entirely — hand-rolled `io(...)` connections with a copy-pasted options object
+  (`timm/ui.html:511-522`, `yolo:330-350`, `image_metrics:614-620`; sam3 connects to the **root**
+  namespace with no namespace at all, `sam3/ui.html:792-794`) and hand-rolled `POST .../run` +
+  `POST .../jobs/{id}/cancel`. The Python side achieved "a plugin never opens its own SocketIO
+  connection" (`job_context.py:97`); the JS side did not.
+- **Proposal:** extend `PluginJobs.run(pluginId, params, handlers)` with `handlers.on = {eventName: fn}`
+  (custom `ctx.emit` events on the same managed socket, subscribed before `/run` fires — the ordering
+  footgun `PluginJobs.on` currently documents away). Add reconnection options matching what the
+  plugins standardized on. Then the four hand-rolled stacks collapse onto the client.
+- Also: stop plugins re-stamping `job_id` into every `ctx.emit` payload (15 occurrences) — the sink
+  already `setdefault`s it (`job_context.py:115`); document that payloads arrive with `job_id`.
+- **Effort:** M. Additive.
+
+### B5. d.ts truth pass (declare what exists, decide what doesn't)
+
+- Add `allowErrorStatus` to `PluginFetchOptions` (implemented at `api-client.js:172-183`, used 13×
+  by the host's own pages) — and note `authFetch`'s auth-blocking and Response-destroying error
+  behavior (`api-client.js:132-140, 182-194`).
+- Complete `TlcLocationApi` (`rowsSpanLocations`, `shortLabel` — `location.js:38-63`) or explicitly
+  tier them out; reconcile ambient `TlcApi` (declares 6 members, implementation exports 20, and the
+  d.ts doc-comment references `encodeObjectUrl`, which it never declares).
+- `libs.cytoscape` is **unconditionally `null`** for plugins — the vendor file is loaded only on
+  `project_detail.html:15`, never on `plugin_host.html`. It's best-effort tier, so: either load it on
+  the plugin page or delete the member at 1.0. Also decide `TlcPptx` (a full deck-builder global on
+  the plugin page with no tier at all) — declare best-effort or hide.
+- Declare the fragment-shape contract prose in the guide: `.plugin-hero h2` rewriting
+  (`plugin-loader.js:244-254`), `[data-provisioning]` lifecycle (`:267-301`), and `plugin-common.css`
+  class stability.
+- **Effort:** S–M. Additive.
+
+### B6. Export the job-runner core to de-duplicate host↔worker terminal logic
+
+- **What/where:** the terminal-event synthesis (`done/cancelled/error` + message format), GPU-reclaim
+  ordering, and the `job_update` reserved-name check exist **twice**: SDK `worker.py:158-171` /
+  `job_context.py:108-110` and host `job_manager.py:262-274, 83, 436-442` — byte-similar
+  reimplementations that must drift-proof by hand.
+- **Proposal:** export `run_job_and_stream(plugin, job_id, params, state_dir, sink, cancel_event)`
+  from the SDK (the `_Job._run` body, made public); host mode calls it too. One implementation of the
+  terminal contract.
+- **Effort:** M (host adopts). Additive.
+
+### B7. Docs drift batch (everything not already inside A6)
+
+- README: base-deps claim (`README.md:46-47` says `3lc` is base), Status section ("0.1 line").
+- `contract.py:8-9` manifest-location claim; delete the orphaned `_ICON_SVG` (`contract.py:32` —
+  guide says "no `_ICON_SVG` import anymore", nothing imports it).
+- `__init__.py:32-33` `sdk_version` manifest claim (per A2/A4 decision).
+- Guide: document undocumented-but-real manifest keys (A4 list) in the interim, fix the
+  `min_input_count = 0` falsy-default footgun host-side (`manifest.py:210` — explicit 0 is silently
+  replaced), correct the isolation-default row until A4 decides it.
+- `frontend/API.md:294-302` stale "add location in the same PR" instruction (already done).
+- **Effort:** S.
+
+---
+
+## C. Process & CI
+
+### C1. Fix the live pins — today, independent of 1.0
+
+- Host + plugins umbrella: `3lc-compute-plugin-sdk[shared]>=0.1.0,<0.2.0` excludes 0.2.0
+  (`3lc-compute/pyproject.toml:24`, `3lc-compute-plugins/pyproject.toml:23`); resolved lock is 0.1.1,
+  so host-mode GPU reclaim, worker `/reclaim`, and `/health` skew-detection are all dead in practice.
+  Bump to `>=0.2.0,<0.3.0`, re-lock, verify the contract test.
+- Frontend: decide the production `contractVersion` story (A2's compute-derived value is the fix; the
+  dev-group-only SDK dep is fine for the d.ts + test).
+- **Effort:** S. Do this first — it's also the dry run for the 1.0 cross-repo bump.
+
+### C2. Mechanical additive-only enforcement (the known wishlist item — confirmed absent)
+
+- CI job in this repo that diffs, against the last release tag: `tlc_plugin_sdk.__all__` + public
+  module symbols (a simple import-and-introspect script), the d.ts interface member sets (extend the
+  frontend's regex parser or use a real TS parser), and — once A4 lands — the manifest schema fields.
+  Removals/renames fail unless the version bump is major. This is what makes "additive-only" and the
+  post-1.0 freeze a property of the repo instead of a promise in the README.
+- **Effort:** M.
+
+### C3. Deepen the frontend conformance test
+
+- `frontend/test_plugin_contract.py` diffs **top-level `PluginApi` names only**. Confirmed blind
+  spots: nested `libs`/`context` shapes, `getConfig` key set, every referenced interface
+  (`TlcData`, `TlcLocationApi`, `TlcApi`, `PluginFetchOptions`, `PluginJobsApi`), signatures, and a
+  second `window.PLUGIN_API` assignment. Dropping `libs.io` — the one STABLE lib — would pass today.
+  Extend to nested object literals and the `getConfig` key union at minimum; `PluginJobsApi` needs a
+  gate on the SDK side (its implementation and declaration live in the same wheel — a unit test
+  comparing `JOB_TRACKER_JS`'s exported names to the d.ts is cheap).
+- **Effort:** M.
+
+### C4. Test the contract itself in this repo
+
+Current suite: 2 files (import-light + GPU reclaim), both good, neither about the contract. Add:
+- `JobContext` event golden-shapes test (each method → exact wire dict; `job_id` stamping; the
+  reserved-name rejection) — this is the schema the host, frontend, and plugins all parse.
+- Worker NDJSON protocol test (start → events → terminal; cancel; the `error` message format) —
+  doubles as the conformance suite the host can run against its in-process runner (B6).
+- `inject_scripts` edge cases; `config_store` round-trip/migration; manifest schema round-trip
+  (post-A4).
+- CI: add a second job with `--extra shared` so mypy actually checks `shared.*` against a real `tlc`
+  (today `tlc`/`PIL`/`torch` are `Any` in CI, which is how `on_status: Any` survives --strict).
+- **Effort:** M.
+
+### C5. Write the release-train checklist
+
+- The 0.2 pin miss (C1) happened because the bump dance spans four repos with no checklist. One page
+  in this repo: bump order (SDK tag → host pin+lock → plugins pin → frontend dev pin), the contract
+  test loop, and the editable-overlay verification recipe.
+- **Effort:** S.
+
+### C6. State the plugin trust model explicitly
+
+- Fragments execute with **full host origin** — `innerHTML` + script re-execution
+  (`plugin-loader.js:198, 257-261`), no iframe/shadow-DOM/CSP anywhere, `TlcAuth` (raw JWT) reachable.
+  With a catalog/install flow shipping (guide's "Publishing via a Catalog"), 1.0 must say out loud:
+  *installing a plugin is executing trusted code in the Hub's origin* — in the guide and the catalog
+  docs. Actual sandboxing is a large frontend project; the honest documented stance is the 1.0
+  deliverable, sandboxing a post-1.0 decision.
+- **Effort:** S (doc) / L (sandboxing, out of scope).
+
+---
+
+## Suggested one-week sequencing
+
+Cross-repo sets are ordered so the contract test + editable overlays keep SDK, host, and frontend
+green at every step. Breaking work lands in two coordinated waves, not a trickle.
+
+**Day 1 — make the current state true (no breaks).**
+C1 pin fixes across host + plugins umbrella (re-lock, contract test). B7 + A6 docs/d.ts truth batch.
+B5 d.ts truth pass. Start C2 freeze-check script (it gates the rest of the week).
+
+**Day 2–3 — breaking wave 1: the reporting/version core (SDK-led).**
+A1 (`ctx.result`/error field) + A2 (version-axis collapse) + A5 prunes/underscorings + B2
+(de-abstract `compute`) land in the SDK as `1.0.0rc1`. Same-day coordinated PRs: host
+(`job_manager` translation + pin `>=1.0.0rc1`), frontend (error field in the panel,
+compute-derived `contractVersion`), plugins (merger/importer `result` rename; timm/yolo/sam3 adopt
+`ctx.result` + delete `job_failed` hand-rolls). Overlay-verify a GPU job end-to-end.
+
+**Day 3–4 — breaking wave 2: the browser surface (frontend-led).**
+A3: frontend implements `PLUGIN_API.pickers.table` + declares CancelJob/toast surface; SDK renames
+`_tlc*` under the declared namespace (aliases kept for the sweep); B1 auto-injection + B4
+`PluginJobs` v2 ship alongside. Then the mechanical plugin sweep (7 plugins × pickers, 5 × `_tlc*`,
+4 × hand-rolled sockets → `PluginJobs`), deleting the four injection idioms and the dead exporter
+injection as you pass through.
+
+**Day 4–5 — the manifest + batteries.**
+A4 `tlc_plugin_sdk.manifest` module; host adopts it (the week's biggest single PR — can trail into
+the next week without blocking the tag if rc-gated). B3 config-route factory + alias context manager
++ `pluginFetch`; delete yolo's store clone and the CRUD quartets in the same sweep.
+
+**Day 5 — lock it.**
+C3 contract-test deepening + C4 golden-shape tests written against the *new* surface (cheaper than
+writing them twice). C2 freeze-check turned on against `v1.0.0`. C5 checklist + C6 trust-model
+paragraph. Tag `1.0.0`.
+
+**Explicitly deferred (fine post-1.0, all additive):** run picker, sandboxing, `modality`
+graduation into `tlc` core (the porting notes in `shared/images.py:13-37` are the plan of record),
+B6 job-runner unification (safe any time).

{3lc_compute_plugin_sdk-0.3.0 → 3lc_compute_plugin_sdk-0.3.2}/CHANGELOG.md

@@ -7,7 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-Nothing yet.
+_Nothing yet._
+
+## [0.3.2] - 2026-08-31
+
+### Fixed
+- Data-source browse fields with a comma-separated `accept` (e.g. `*.yaml,*.yml`, `*.pt,*.pth`)
+  now list matching files; previously they showed none. `/browse` was matching the whole
+  `accept` string as one literal glob pattern instead of any pattern in the list.
+  ([#28](https://github.com/3lc-ai/3lc-compute-plugin-sdk/pull/28))
+
+## [0.3.1] - 2026-08-27
+
+A patch on the 0.3 line, additive and pin-compatible (`>=0.3.0,<0.4.0` resolves it). The SDK now
+brings the `3lc` data plane as a base dependency, and the shared data-source browse widget gains an
+input/output picker split.
+
+### Added
+- The shared data-source browse widget shows a small caption ("Showing files matching:
+  `<glob>`") when a field declares an `accept` glob, so users understand why some files in a
+  listed folder don't appear as selectable — folders themselves are never glob-filtered.
+
+### Changed
+- **`3lc[pandas]` is now a base dependency.** Installing `3lc-compute-plugin-sdk` brings the 3LC
+  data plane, so a plugin pins the SDK alone and gets `tlc` and every `shared.*` helper with it.
+  The former `[shared]` extra is kept as an empty, deprecated alias — existing
+  `3lc-compute-plugin-sdk[shared]` pins keep resolving — and will be removed at 1.0. Drop the
+  suffix when you raise your floor to a release carrying this change. Nothing changes at import
+  time: `tlc` is still loaded lazily, only by the helpers that use it.
+- **Docs:** clarified `runtime.provision_extra` in the plugin guide — it names the
+  optional-dependency group the host installs into your plugin's venv (keeping the base light for
+  discovery and letting one distribution carry several plugins), not an "umbrella-only, required"
+  key. Restated that isolation is venv-only: every plugin runs from a host-built managed venv,
+  with no in-process/host mode and no `.venv` beside the source. No contract or code change.
+- **Data-source browse widget:** the widget now takes a `purpose` config axis (`'input'`, the
+  default, or `'output'`), mirrored by a `purpose` query param on `/browse`. Input pickers now
+  **hide** folders the compute process cannot open (rather than showing them disabled), so the
+  listing only offers places you can actually descend into. Output pickers show **all** folders
+  and instead flag the ones that are not writable — dimmed with a lock glyph and a tooltip, but
+  still navigable so you can descend to a writable subdirectory — and disable "Select This
+  Folder" when the current directory is not writable. In output mode `/browse` returns a
+  `writable` flag on each directory entry and for the listed directory itself (computed only in
+  output mode; an older host that omits the flag is treated as writable).
+
+### Fixed
+- **Data-source browse widget:** folders the compute process cannot actually open (e.g. macOS
+  TCC-protected packages like `Photos Library.photoslibrary`) are now marked inaccessible and
+  rendered disabled — dimmed, with a lock glyph and a tooltip — instead of listed as navigable
+  and then failing with a red "Permission denied" panel when clicked. The `/browse` route probes
+  each directory's openability with `os.scandir` (not `os.access`, which TCC packages spuriously
+  pass) and tags directory entries with an `accessible` flag; an older host that omits the flag
+  keeps working (entries are treated as accessible).
 
 ## [0.3.0] - 2026-08-25
 

{3lc_compute_plugin_sdk-0.3.0 → 3lc_compute_plugin_sdk-0.3.2}/CLAUDE.md

@@ -18,16 +18,16 @@ in a separate repository and is **not** a dependency of this SDK.
    host-side). The SDK is the root of the dependency graph; the host depends on the SDK, never the
    reverse. The whole point — a plugin built against just this wheel runs in its own isolated venv.
 2. **Import-light.** Importing `tlc_plugin_sdk` must not eagerly pull the server stack *or the data
-   plane*. `litestar` and `uvicorn` are base deps but are imported **lazily** (only when a worker
-   actually serves); `tlc` is an optional extra imported lazily only by `shared.*`; and the
-   host-only SocketIO server must not be importable from here at all. `tests/test_import_light.py`
-   enforces this (guards `litestar`/`socketio`/`uvicorn`/`tlc`) — keep it green.
-3. **Dependencies stay minimal.** Base = `uvicorn` + `litestar` only. `3lc` is an optional extra
-   (`3lc-compute-plugin-sdk[shared]`, named for the `shared.*` module it unlocks) used solely by those
-   helpers — the contract core needs no data plane, so light consumers (e.g. the Hub frontend)
-   install the bare SDK. Adding a base dep widens what every plugin venv must install — justify it.
-   (Direction: as `shared.*` graduates into the core, `3lc` likely returns to base with `[shared]`
-   kept as a no-op alias.)
+   plane*. `litestar`, `uvicorn`, and `tlc` are all base deps but are imported **lazily** — the
+   server stack only when a worker actually serves, `tlc` only inside the `shared.*` helpers that
+   use it; and the host-only SocketIO server must not be importable from here at all.
+   `tests/test_import_light.py` enforces this (guards `litestar`/`socketio`/`uvicorn`/`tlc`) —
+   keep it green. Import-light is about worker startup time, not about what is installed.
+3. **Dependencies stay minimal.** Base = `uvicorn` + `litestar` + `3lc[pandas]`, nothing else.
+   `3lc` is deliberately a base dep, not an extra: every real plugin uses the data plane, and making
+   it optional only created a way to build a venv that imports fine and fails on first use. (The
+   `[shared]` extra it used to live behind is an empty, deprecated alias — gone at 1.0.) Adding a
+   base dep widens what every plugin venv must install — justify it.
 4. **The contract is published — every public symbol is forever-ish.** The 0.x line is
    additive-only (see README → Status): additions are the safe move; reshaping
    `JobContext`/`ComputePlugin` waits for a major bump. The version is the contract version
@@ -50,9 +50,8 @@ and how to port an existing plugin.
 
 ## Dev setup
 
-`3lc` resolves from the public 3LC releases index (`[tool.uv.index]` in `pyproject.toml`). If
-your platform lacks a prebuilt wheel there, override locally (uncommitted) with an editable
-path source.
+`3lc` resolves from public PyPI. To develop against an unreleased `3lc`, override locally
+(uncommitted) with an editable path source in `[tool.uv.sources]`.
 
 ```bash
 uv sync                 # installs the SDK + dev tools (ruff, mypy, pytest)

{3lc_compute_plugin_sdk-0.3.0 → 3lc_compute_plugin_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 3lc-compute-plugin-sdk
-Version: 0.3.0
+Version: 0.3.2
 Summary: Public Python SDK for building 3LC compute-service plugins.
 Project-URL: Homepage, https://github.com/3lc-ai/3lc-compute-plugin-sdk
 Project-URL: Repository, https://github.com/3lc-ai/3lc-compute-plugin-sdk
@@ -18,10 +18,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: 3lc[pandas]<4.0.0,>=3.0.0
 Requires-Dist: litestar<3.0.0,>=2.22.0
 Requires-Dist: uvicorn>=0.34.0
 Provides-Extra: shared
-Requires-Dist: 3lc[pandas]<4.0.0,>=3.0.0; extra == 'shared'
 Description-Content-Type: text/markdown
 
 # 3lc-compute-plugin-sdk
@@ -72,11 +72,12 @@ stance.
 
 ## How it fits
 
-This SDK sits at the root of the plugin dependency graph. Its only required dependencies are
-`uvicorn` and `litestar`; the `3lc` data plane is an optional extra
-(`3lc-compute-plugin-sdk[shared]`), pulled in only by the `shared.*` helpers. It **never** depends
-on the compute service itself or on any plugin. A plugin built against `tlc_plugin_sdk` alone is
-therefore portable across service versions and runs in its own isolated environment.
+This SDK sits at the root of the plugin dependency graph. Its dependencies are `uvicorn`,
+`litestar`, and the `3lc` data plane (`3lc[pandas]`) — so installing the SDK is all a plugin needs
+to use `tlc` and the `shared.*` helpers built on it. All three are imported lazily; `import
+tlc_plugin_sdk` stays cheap. It **never** depends on the compute service itself or on any plugin.
+A plugin built against `tlc_plugin_sdk` alone is therefore portable across service versions and
+runs in its own isolated environment.
 
 ## Status
 

{3lc_compute_plugin_sdk-0.3.0 → 3lc_compute_plugin_sdk-0.3.2}/README.md

@@ -46,11 +46,12 @@ stance.
 
 ## How it fits
 
-This SDK sits at the root of the plugin dependency graph. Its only required dependencies are
-`uvicorn` and `litestar`; the `3lc` data plane is an optional extra
-(`3lc-compute-plugin-sdk[shared]`), pulled in only by the `shared.*` helpers. It **never** depends
-on the compute service itself or on any plugin. A plugin built against `tlc_plugin_sdk` alone is
-therefore portable across service versions and runs in its own isolated environment.
+This SDK sits at the root of the plugin dependency graph. Its dependencies are `uvicorn`,
+`litestar`, and the `3lc` data plane (`3lc[pandas]`) — so installing the SDK is all a plugin needs
+to use `tlc` and the `shared.*` helpers built on it. All three are imported lazily; `import
+tlc_plugin_sdk` stays cheap. It **never** depends on the compute service itself or on any plugin.
+A plugin built against `tlc_plugin_sdk` alone is therefore portable across service versions and
+runs in its own isolated environment.
 
 ## Status