release: promote release/0.5.x to main for v0.5.10#197
Merged
Conversation
…ted, fail-fast server/src/config.ts that is the only file permitted to read process.env (enforced by an ESLint no-restricted-syntax ban), route all thirty-one scattered reads through it, unify the four disagreeing STORAGE_PATH/FOVEA_MODE/MODEL_SERVICE_URL/OTEL defaults, validate API_KEY_ENCRYPTION_KEY and the production SESSION_SECRET at startup, and bump every package to 0.5.0 to open the release cycle.
refactor: backend configuration single-source-of-truth (Phase 1a, opens 0.5.0)
…ANGELOG.md section and creates or updates the GitHub Release on every version-tag push, kept independent of the image-build job so a Release is published even when the heavy model-service-gpu image hits the ninety-minute timeout, closing the gap that left v0.4.3 without a GitHub Release.
…ub-release fix: release.yml auto-creates GitHub Releases on tag push
…frozen annotation-tool/src/config.ts that is the only file permitted to read import.meta.env (enforced by an ESLint no-restricted-syntax ban), resolve the mode and demo build flags into one derived deploymentMode object with documented precedence, remove the two import.meta cast hacks and the dead VITE_MODEL_SERVICE_URL declaration, normalize the inconsistent VITE_E2E checks, and keep the three tree-shaking-critical MSW guards inline so Rollup still drops the mocks subtree from normal production builds.
refactor: frontend configuration single-source-of-truth (Phase 1b)
…s module that owns all environment access, validated once and instantiated at the top of the FastAPI lifespan for fail-fast startup, route all thirteen scattered os.environ reads through it with a guard test asserting none remain elsewhere, subsume the two divergent MODEL_CONFIG_PATH resolution sites into one, and preserve the existing models.yaml discriminated-union catalog validation, the OTEL two-default behavior, and the HUGGING_FACE_HUB_TOKEN/HF_TOKEN alias semantics.
…e-settings refactor: model-service configuration via pydantic-settings (Phase 1c)
…red into the backend lint job via pnpm check:env) that fails when .env.example declares a duplicate key or omits a backend config key, document the previously-absent SESSION_IDLE_TIMEOUT_MINUTES, ALLOW_TEST_ADMIN_BYPASS, DEFAULT_USER, MODEL_SERVICE_ADMIN_TOKEN, AWS credential, and demo/tours variables in .env.example, derive one config.deploymentMode summary logged once at startup, and add an operations configuration guide documenting the single-source-of-truth model across all three services.
…-guard refactor: config drift guard + deploymentMode summary + config docs (Phase 1d, completes Phase 1)
…a package.json packageManager field (pnpm@10.15.0) with engines.node, parameterize every Dockerfile Node base via ARG NODE_VERSION to converge the production images from Node 20 to 22, and switch every CI workflow to node-version-file plus packageManager-resolved pnpm while removing the stray Node 20 in the deploy workflow, with the backend and frontend images both validated by a local Node 22 build.
build: pin Node and pnpm in one place, converge images to Node 22 (Phase 2a)
…figurations with their documented override chains and profiles and remove the prior two-file check from docker.yml, and set THUMBNAIL_OUTPUT_ROOT on the model-service and model-service-gpu services so generated thumbnails land in the shared /videos mount the backend reads instead of the container-local /tmp/thumbnails default.
…dation build: validate all 10 compose files in CI + fix model-service thumbnail path (Phase 2b)
…tgres, Redis, and the observability stack with conflicting user/password credentials and a separate volume, repoint the dev:infra, dev:infra:full, stop, and clean scripts onto the root docker-compose.yml and its dev overlay so local development shares one Postgres definition and the canonical fovea credentials, and drop its line from the verify-compose CI job.
…nsolidation build: consolidate dev infra onto the root compose stack, resolve the Postgres credential conflict (Phase 2c)
…figured test tree by moving tests/infrastructure into test/infrastructure and deleting the duplicate, so the 118 architecture-registry and per-family loader-factory tests that pytest.ini's testpaths=test never collected now run in the standard suite.
…test-trees test: consolidate the model-service's orphaned test tree so 118 uncollected tests run (Phase 3a)
…ntrypoint that fans out to all four components (Node via pnpm, Python via uv) and repoint the README and CONTRIBUTING test and quality instructions at it, replacing the previously-divergent per-package recipes that had drifted between npm and pnpm and between bare pytest and uv run pytest.
…-entrypoint build: add a root Makefile as the single build/test entrypoint, point docs at it (Phase 3b)
…ows README to match the actual jobs and triggers, removing the permanently disabled test-e2e job from ci.yml since end-to-end tests run in the dedicated e2e-mock and e2e-real-models workflows, listing test-model-service in the quality gate as advisory rather than falsely reporting it as skipped for disk-space, and correcting DOCKER_QUICK_REFERENCE to reference SESSION_SECRET instead of the non-existent COOKIE_SECRET.
…ation docs: reconcile CI workflows README + quality gate with reality (Phase 3c)
…KEY at boot, which crash-looped every backend container whose compose file does not set that feature-gated key, by validating the key format only when it is set while leaving the lazy use-time check intact so deployments without API-key management boot normally.
…-overreach fix: don't require API_KEY_ENCRYPTION_KEY at boot (backend crash-loop regression)
…s) and PersonaService (orchestration plus RBAC), reducing routes/personas.ts from 1641 lines with 44 direct prisma calls to 640 thin lines with none, and expose Persona.projectId in the response schema and frontend type for project-scoped persona browsing.
…us userId plus testId) so two persistence tests on the same worker no longer create two same-named personas, which made the persona dropdown resolve to multiple options and fail the strict-mode locator under concurrent load.
…rvice-repo refactor: extract personas into a service/repository layer (Phase 4.1)
…ce and migrate its authorization onto CASL by making Project a first-class subject that replaces the inline project_owner/project_manager role-string and isAdmin checks, and add a project-scoped assignable-users endpoint so the member-add picker works for non-admin owners and managers.
…rvice-repo refactor: extract the projects domain to a service/repository layer and migrate it onto CASL
…ducing routes/claims.ts from 1559 lines with 33 direct prisma calls to 783 thin lines with none, by relocating the existing CASL authorization, the claimsJson rebuild, the claim-extraction and synthesis queue jobs, the auto-created empty summary, and the subclaim cascade verbatim with no behavior change.
…ss-per-file loaders subpackages with a shared base, keeping each loader.py as a thin aggregator that re-exports the public surface and imports every per-loader module so registration still runs on import and no consumer import path changes.
…ce-loader-split refactor: split the model-service VLM and detection loaders one-class-per-file
…auditable demo-rbac module that holds the per-subject demo read scopes and predicates and gates each on isDemoModeEnabled internally, migrating all eleven route and service sites so no handler scatters the flag check while preserving every effective query and decision byte-for-byte.
…g-casl-helper refactor: consolidate demo-mode RBAC read-widening into one auditable module
…sive hooks under components/annotation/hooks (useAnnotationDialogs for the dialog and transcript state, useSummaryFlow for the claim timestamp-capture and draft-claim flow, and useAnnotationState for the playback state, keyframe and edit handlers, and autosave setup), leaving the component a thin composition of the hooks plus its render with state, effects, dependency arrays, handler logic, and output unchanged.
…-workspace-decomposition refactor: decompose AnnotationWorkspace into useAnnotationDialogs/useSummaryFlow/useAnnotationState hooks
…c in a code span so the generated API doc is valid MDX and the documentation site build no longer fails on an unclosed JSX tag.
…no generated API-doc description begins with a lowercase import or export keyword, which the Docusaurus MDX parser otherwise mistakes for an ESM statement and which broke the documentation site build.
* Accept non-UUID video ids in the admin video-assignment endpoints by giving every video id field a minimum-length string schema while keeping the project and user ids uuid-constrained. * Exempt the video stream and thumbnail routes from the global per-IP rate limiter so a saturated request budget can no longer return a 429 JSON body in place of media bytes. * Surface annotation save failures to the annotator by routing the single-write mutation errors and the batch auto-save's collected per-annotation failures through a toast instead of swallowing them. * Reduce the frontend request fan-out and recover from stream failures by lazily loading grid thumbnails, giving the persona-ontology query a normal stale time, stopping client-error retries and window-focus refetches, and adding a video-player retry overlay. * Show the selected item's name instead of a raw UUID in the closed trigger of every id-bound select by passing a value-to-label render function at each call site. * Fix the annotate workspace header so a long description no longer collapses the player, the persona select wraps its open list, and the title falls back to the video title for file-synced videos without an uploader. * Make the persona builder readable by expanding long descriptions on demand, wrapping the detail-header description, scoping the persona list to the active project, and defaulting project members into their first project. * Bump the version to 0.5.1 and record the field-reported bug-fix batch in both changelogs. * Regenerate the server OpenAPI spec and the frontend API types so the committed contract artifacts reflect the loosened video-assignment video-id schema. * release: promote release/0.5.x to main for v0.5.0 (#171) * Centralize all backend environment access into a single typed, validated, fail-fast server/src/config.ts that is the only file permitted to read process.env (enforced by an ESLint no-restricted-syntax ban), route all thirty-one scattered reads through it, unify the four disagreeing STORAGE_PATH/FOVEA_MODE/MODEL_SERVICE_URL/OTEL defaults, validate API_KEY_ENCRYPTION_KEY and the production SESSION_SECRET at startup, and bump every package to 0.5.0 to open the release cycle. * Add a create-release job to release.yml that extracts the matching CHANGELOG.md section and creates or updates the GitHub Release on every version-tag push, kept independent of the image-build job so a Release is published even when the heavy model-service-gpu image hits the ninety-minute timeout, closing the gap that left v0.4.3 without a GitHub Release. * Centralize all frontend environment access into a single typed, deep-frozen annotation-tool/src/config.ts that is the only file permitted to read import.meta.env (enforced by an ESLint no-restricted-syntax ban), resolve the mode and demo build flags into one derived deploymentMode object with documented precedence, remove the two import.meta cast hacks and the dead VITE_MODEL_SERVICE_URL declaration, normalize the inconsistent VITE_E2E checks, and keep the three tree-shaking-critical MSW guards inline so Rollup still drops the mocks subtree from normal production builds. * Promote the model-service to a single typed pydantic-settings Settings module that owns all environment access, validated once and instantiated at the top of the FastAPI lifespan for fail-fast startup, route all thirteen scattered os.environ reads through it with a guard test asserting none remain elsewhere, subsume the two divergent MODEL_CONFIG_PATH resolution sites into one, and preserve the existing models.yaml discriminated-union catalog validation, the OTEL two-default behavior, and the HUGGING_FACE_HUB_TOKEN/HF_TOKEN alias semantics. * Add a CI configuration-drift guard (scripts/check-env-example.mjs, wired into the backend lint job via pnpm check:env) that fails when .env.example declares a duplicate key or omits a backend config key, document the previously-absent SESSION_IDLE_TIMEOUT_MINUTES, ALLOW_TEST_ADMIN_BYPASS, DEFAULT_USER, MODEL_SERVICE_ADMIN_TOKEN, AWS credential, and demo/tours variables in .env.example, derive one config.deploymentMode summary logged once at startup, and add an operations configuration guide documenting the single-source-of-truth model across all three services. * Pin Node and pnpm in one place by adding a root .nvmrc (Node 22) and a package.json packageManager field (pnpm@10.15.0) with engines.node, parameterize every Dockerfile Node base via ARG NODE_VERSION to converge the production images from Node 20 to 22, and switch every CI workflow to node-version-file plus packageManager-resolved pnpm while removing the stray Node 20 in the deploy workflow, with the backend and frontend images both validated by a local Node 22 build. * Add a verify-compose CI job that validates all ten docker compose configurations with their documented override chains and profiles and remove the prior two-file check from docker.yml, and set THUMBNAIL_OUTPUT_ROOT on the model-service and model-service-gpu services so generated thumbnails land in the shared /videos mount the backend reads instead of the container-local /tmp/thumbnails default. * Delete the duplicate server/docker-compose.dev.yml that redefined Postgres, Redis, and the observability stack with conflicting user/password credentials and a separate volume, repoint the dev:infra, dev:infra:full, stop, and clean scripts onto the root docker-compose.yml and its dev overlay so local development shares one Postgres definition and the canonical fovea credentials, and drop its line from the verify-compose CI job. * Consolidate the model-service's orphaned tests directory into the configured test tree by moving tests/infrastructure into test/infrastructure and deleting the duplicate, so the 118 architecture-registry and per-family loader-factory tests that pytest.ini's testpaths=test never collected now run in the standard suite. * Add a root Makefile as the single install/lint/typecheck/test/build entrypoint that fans out to all four components (Node via pnpm, Python via uv) and repoint the README and CONTRIBUTING test and quality instructions at it, replacing the previously-divergent per-package recipes that had drifted between npm and pnpm and between bare pytest and uv run pytest. * Reconcile CI documentation with reality by rewriting the stale workflows README to match the actual jobs and triggers, removing the permanently disabled test-e2e job from ci.yml since end-to-end tests run in the dedicated e2e-mock and e2e-real-models workflows, listing test-model-service in the quality gate as advisory rather than falsely reporting it as skipped for disk-space, and correcting DOCKER_QUICK_REFERENCE to reference SESSION_SECRET instead of the non-existent COOKIE_SECRET. * Stop the startup config validation from requiring API_KEY_ENCRYPTION_KEY at boot, which crash-looped every backend container whose compose file does not set that feature-gated key, by validating the key format only when it is set while leaving the lazy use-time check intact so deployments without API-key management boot normally. * Extract the personas domain into a PersonaRepository (pure data access) and PersonaService (orchestration plus RBAC), reducing routes/personas.ts from 1641 lines with 44 direct prisma calls to 640 thin lines with none, and expose Persona.projectId in the response schema and frontend type for project-scoped persona browsing. * Make the persistent test persona name unique per test (workerIndex plus userId plus testId) so two persistence tests on the same worker no longer create two same-named personas, which made the persona dropdown resolve to multiple options and fail the strict-mode locator under concurrent load. * Extract the projects domain into a ProjectRepository and ProjectService and migrate its authorization onto CASL by making Project a first-class subject that replaces the inline project_owner/project_manager role-string and isAdmin checks, and add a project-scoped assignable-users endpoint so the member-add picker works for non-admin owners and managers. * Extract the claims domain into a ClaimRepository and ClaimService, reducing routes/claims.ts from 1559 lines with 33 direct prisma calls to 783 thin lines with none, by relocating the existing CASL authorization, the claimsJson rebuild, the claim-extraction and synthesis queue jobs, the auto-created empty summary, and the subclaim cascade verbatim with no behavior change. * Extract the world-state domain into a WorldStateRepository and WorldStateService, reducing routes/world.ts from 1148 lines with 27 direct prisma calls to 372 thin lines with none, by relocating the existing CASL authorization, the demo and single-user read handling, the existence-privacy forbidden-versus-not-found logic, and the entity, event, and time object-reference gloss cleanup verbatim with no behavior change. * Split the 2232-line import-handler.ts import state machine into focused modules under services/import (line-parser, dependency-graph, conflict-resolver, an EntityImporter collaborator, and types), leaving import-handler.ts a 517-line orchestrator that still wraps the whole import in the same interactive transaction, with routes/import.ts and the public ImportHandler API unchanged. * Stand up the OpenAPI to frontend-types generation pipeline by emitting a committed server openapi.json and generating annotation-tool API types from it with openapi-typescript, replacing the hand-copied detection and ontology-augmentation contract types and a snake_case OntologyAugmenter casing bug with types derived from the spec, and add a contract-drift CI job that fails when the committed spec or generated types are stale. * Decouple the model-service contract layer from the ML stack by removing the eager submodule re-exports from the infrastructure __init__ files so a Pydantic request or response DTO imports without transitively loading cv2 via the outbound video processor, and raise the opencv-python floor to 4.10 so the resolver cannot select the numpy-1-ABI 4.9.x that fails against the numpy 2 the audio stack requires. * Add the server↔model-service contract pipeline by emitting a committed ML-free OpenAPI 3.1 spec from the model-service pydantic schemas, generating server TypeScript types from it, and adding compile-time compatibility assertions plus a blocking CI drift gate so a model-service field drop, rename, or retype becomes a tsc error naming the field rather than a runtime surprise, and correct the latent ModelSummarizeResponse key_frames annotation the guard surfaced. * Resolve cross-user object names server-side by adding an optional linkedObjectName to the annotations list response, looked up from the annotation owner's world in a single batched query gated by the existing accessibleBy read filter, and use it as a fallback badge label in AnnotationOverlay when the caller's own world cannot resolve the object. * Make POST /api/annotations idempotent on an optional client-supplied id by updating the existing annotation in place via the same can('update') gate as PUT when the id already exists, creating with that id otherwise, and collapsing a concurrent-create race to a single row via a P2002 fallback to the update path, so a lagged autosave re-POST of an already-persisted box no longer mints a duplicate. * Fix the annotation autosave idle loop and box duplication by stripping server-managed fields from useAutoSave change detection and sending the stable client id on create, and fix a silent data-loss bug the loop had masked where keyframe and drag-resize edits forced a save in the same tick as the cache mutation and persisted the pre-edit array, by returning the freshly-computed array from the mutation hooks and threading it through forceSave with a data override. * Split the model-service vlm and detection loader modules into one-class-per-file loaders subpackages with a shared base, keeping each loader.py as a thin aggregator that re-exports the public surface and imports every per-loader module so registration still runs on import and no consumer import path changes. * Consolidate the scattered demo-mode RBAC read-widening into a single auditable demo-rbac module that holds the per-subject demo read scopes and predicates and gates each on isDemoModeEnabled internally, migrating all eleven route and service sites so no handler scatters the flag check while preserving every effective query and decision byte-for-byte. * Decompose the 1403-line AnnotationWorkspace component into three cohesive hooks under components/annotation/hooks (useAnnotationDialogs for the dialog and transcript state, useSummaryFlow for the claim timestamp-capture and draft-claim flow, and useAnnotationState for the playback state, keyframe and edit handlers, and autosave setup), leaving the component a thin composition of the hooks plus its render with state, effects, dependency arrays, handler logic, and output unchanged. * Finalize the 0.5.0 changelog date to the release date. * Wrap the literal video tag in the useAnnotationState return-type JSDoc in a code span so the generated API doc is valid MDX and the documentation site build no longer fails on an unclosed JSX tag. * Reword the import-module JSDoc and the ImportResultDialog summary so no generated API-doc description begins with a lowercase import or export keyword, which the Docusaurus MDX parser otherwise mistakes for an ESM statement and which broke the documentation site build. * Set the 0.5.0 changelog release date to the 2026-06-22 tag date in both changelog files. * Remove the tour-run test helpers that were accidentally swept into the merge commit; they belong with the 0.5.2 tour-engine work, not the 0.5.1 fixes.
…oth changelog files.
…ge, keeping the 0.5.1 version, changelog, and contract artifacts while adopting main's release-workflow GPU-build removal.
…am provider so Safari's pause and resume range requests no longer crash to a black player, promote the paused video element onto its own WebKit compositing layer, add cross-browser pause and resume E2E coverage under chromium webkit and firefox, and bump to 0.5.2. (#175)
…both changelogs. (#178)
… can see project content (#181) * Stamp the persona's project scope on every video summary and claim write so project collaborators can read project content and add claims under it, backfill existing NULL-scoped rows, expose projectId on the summary and claim API responses, and add unit, integration, and E2E coverage. * Thread the requesting user through the summarization and claim-extraction queue payloads so model-generated summaries and extracted claims are stamped with createdBy and remain readable by their creator. * Bump the patch version to 0.5.4 and record the summary and claim project-scope and ownership stamping fixes in both changelogs.
…ge, keeping the 0.5.4 version, changelog, contract artifacts, and the project-scope stamping fix while making main an ancestor again.
…lineage (trees identical; history-only) so the next promote is clean.
…validation, non-clobbering world-state persistence with explicit object deletes, personaless-annotation project scope, claim-create idempotency, duplicate-assignment conflict handling, summary comment autosave, claim-relation and ability-mirror cache invalidation, and isAdmin/systemRole sync, and bump the version to 0.5.5 (#186)
…lineage (trees identical; history-only) so the next promote stays clean.
…s, idempotent conflict-safe creates, lost-update merge-by-id on ontology/project/import world state, atomic world-object deletions, and deep-fork of shared resources, bumping to 0.5.6 (#188)
…lineage (trees identical; history-only) so the next promote stays clean.
* Fix frontend data-loss and stale-cache defects: trigger autosave on comment-only edits via value-based change detection, flush pending edits on dialog Escape/backdrop dismiss and on session expiry, guard the retry path against concurrent saves, and invalidate the sharing, project/group list, summary-lookup, annotation, and world caches on the mutations that affect them. * Bump the version to 0.5.7 for the frontend data-loss and cache patch. * Route ontology entity/role/event/relation-type deletion through the explicit delete endpoint instead of an omission PUT, which the 0.5.6 merge-by-id ontology write now treats as a no-op (the omitted type was kept and re-seeded on refetch). * Add a regression guard asserting ontology type deletion hits the explicit DELETE endpoint rather than an omission PUT. * Add the 0.5.7 changelog entry to both changelog files for the frontend data-loss and cache patch.
…lineage (trees identical; history-only) so the next promote stays clean.
…path, offload blocking inference off the event loop, bound ffprobe/ffmpeg waits with timeout-and-kill, guard concurrent model loads with a reentrant lock and re-check, read the configured video root, and compare the admin token in constant time, bumping to 0.5.8 (#192)
…lineage (trees identical; history-only) so the next promote stays clean.
… on the model-proxy routes and admin on model state changes, enforcing project membership on persona creation and instance-level authorization on import replaces, replacing the millisecond-collidable updatedAt optimistic guard with a monotonic version column across world state and ontologies, making persona and ontology-type deletion transactional, mapping duplicate creates to 409 including a partial unique index for admin API keys, deep-forking a shared summary's claims, and bumping to 0.5.9 (#194)
…lineage (trees identical; history-only) so the next promote stays clean.
… save issued while another is in flight and reporting whether it actually wrote, flushing and remounting the summary editor on a persona switch, seeding the auto-save baseline to just-loaded content so opening the editor no longer fires a spurious save, counting only real writes in the session-expiry emergency flush, and invalidating the annotation, world, project-persona, and per-persona ontology caches that ontology-type deletes, world-object deletes, persona create/delete, and concurrent ontology writes were leaving stale, bumping to 0.5.10 (#196)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Promotes
release/0.5.xtomainfor the v0.5.10 patch — the frontend slice and second of three patches remediating the second swarm audit (landed in #196). The diff againstmainis exactly the 0.5.10 changes.0.5.10 fixes auto-save data-loss and stale-cache defects in the annotation UI: a forced save dropped while another was in flight, a persona switch that lost or cross-wrote edits, an emergency flush that over-reported preservation, a spurious save on dialog open, and stale annotation/world/project-persona/per-persona-ontology caches after ontology-type deletes, world-object deletes, persona create/delete, and concurrent ontology writes. Several were gaps in the first audit's own frontend fixes. Nothing is breaking. See the 0.5.10 changelog entry. This is the second of three patches (0.5.9 backend, 0.5.10 frontend, 0.5.11 model-service) remediating the second audit.
Type of Change
Related Issues
Promotes #196.
Changes Made
release/0.5.xtomain.Testing
Test Environment
Test Cases
How to Test
useAutoSaveforce-queue / outcome / baseline-seeding tests and anautoSaveRegistrycounting test.waitForResponserace, not code regressions).Screenshots/Videos
N/A
Documentation
Performance Impact
Details: The auto-save retry is now an awaited loop within one invocation (same backoff, guard held throughout); the added cache invalidations refetch already-active queries.
Breaking Changes
Breaking changes:
Migration guide:
Checklist
Additional Notes
Squash-merge, then tag
v0.5.10(Latest) and reconcilemain→release/0.5.xper the established cycle.Reviewer Guidance
The net diff is exactly the 0.5.10 frontend hardening already reviewed and merged in #196.