AncestryLLM 0.6.0

AncestryLLM 0.6.0 advances the Astral tooling modernization, hardens the packaged desktop sidecar lifecycle, and completes the v0.6 Diátaxis documentation cutover alongside the v0.5.0 desktop foundation.

Highlights

  • Issue #200 adds shared native mutation ownership and restart recovery for settings, sync generations, RootsMagic exports, and artifact publication. Single files and directories retain atomic publication; legacy separate filenames retain their paths with journaled complete-set recovery. The account-scoped journal contains coordination metadata only, and recovery requires renewed authorization. Internal terminal history and unused lock files are collected without discarding retry or recovery authority. Sync retries that recover a committed generation require selecting its recovered master and manifest before continuing. Local source checks and hosted/platform evidence are tracked separately in mutation recovery.

  • Native Windows ARM64 sidecar startup now avoids recursive per-table SQLCipher reflection. Empty workspaces bootstrap revision 0002 directly, while partial, unknown, or unexpected schema layouts continue to fail closed without implicit repair. The packaged 0001 to 0002 migration now begins one native SQLite transaction before DDL, so a late failure leaves neither job table nor its indexes behind.
  • Packaged diagnostics tests now consume the production shared contract and compare its stable required fields while allowing the complete sanitized report returned by Electron Main. Ubuntu packaged and installer checks use a disposable distribution-provided GNOME Secret Service on a private D-Bus session, with no alternate keyring backend or retained runner credentials. Normal Linux launches retain only the native D-Bus address and XDG runtime directory needed to reach the user’s Secret Service. A separate unpublished verifier package passes its owner-only root through an exact Linux-only switch; the production package contains no selector and is assembled and scanned first. Main derives the verifier’s temporary home and XDG paths without inheriting ambient values. Installer verification runs the installed production package against a disposable native service at the owner-only /run/user/<uid>/bus endpoint that production Main derives. It creates and identity-tracks a private bus when the endpoint is absent, or reuses an existing current-user live bus only after proving the socket is stable and the Secret Service name is unowned; a reused bus is never killed or removed.
  • Packaged desktop startup now verifies an embedded-digest-bound, exact target/build payload inventory before token generation or process spawn, rejects payload and protocol/build mismatches, bounds crash retries, and supervises full POSIX and Windows process trees through shutdown. Integrity failures preserve the crash-restart budget and recover only through the separately bounded manual retry after the payload is repaired.
  • A failed or timed-out bounded sidecar shutdown remains a failed quit attempt, but a later quit request can retry termination instead of reusing a rejected promise forever. Electron now invalidates the public active session before a hidden, authenticated, bodyless request asks Uvicorn to begin its normal graceful drain. A 204 response is not termination proof: Main must observe the sidecar exit or use the existing forced process-tree fallback. The complete supervisor path remains bounded to 20 seconds. The Windows taskkill.exe helper and its adapter are both bounded to four seconds, after which Electron still requires an independently observed process exit. Installed Windows builds allow a bounded five-second observation window so a delayed leader-exit notification does not turn a successful shutdown into a false timeout. Private working-directory removal retries transient Windows filesystem errors for a bounded interval, while a persistent cleanup failure continues to veto exit.
  • Packaged Windows and Linux verification now requests the final native window close and requires Electron itself to exit cleanly. Windows sends an operating-system WM_CLOSE message to the unique top-level window whose owner PID matches the launched package and whose caption exactly matches the application-controlled AncestryLLM title; Linux uses Chromium’s page-close request with unload handling enabled. The gate does not broadcast the request or substitute renderer JavaScript, raw CDP browser shutdown, force termination, or a production-only verifier hook for the application lifecycle.
  • Packaged shutdown timeout evidence now includes only exact, bounded lifecycle phase or failure codes. Arbitrary process output, environment values, response bodies, and local paths are not retained, so release diagnostics can identify the stalled shutdown phase without broadening the evidence surface.
  • Schema-v1 job snapshots and monotonic events are persisted in SQLCipher with bounded history, subscribers, queues, payloads, and list results. Fixed authenticated routes provide list, status, idempotent cooperative cancellation, SSE replay with coded resynchronization, and safe-shutdown assessment. Startup reconciliation records exactly one failed terminal state for interrupted work without replaying side effects.
  • Electron Main now waits for the safe-shutdown assessment and, while protected work remains active, presents native Wait, Request cancellation, and Stay open choices. Cancellation can remain pending until a safe point; atomic publication is never silently abandoned. Signal handling and supervisor ownership now precede asynchronous sidecar startup; shutdown cancels pre-spawn work and drains an in-flight process launch before exit. The explicit empty shortcut is available only before any authenticated session has been exposed. This source change adds no renderer job workflow, submission route, or provider stream.
  • The 0.6.0 source adds a Tasks destination that rebuilds from backend snapshots, follows bounded sender-owned events, shows distinct safe cancellation phases and coded errors, and presents only path-free artifact metadata. It adds no task admission, direct artifact action, provider execution, or genealogy operation.
  • The 0.6.0 Python sidecar source adds a synchronous transient-chat API that accepts only an exact stored provider profile and model, repeats policy and consent checks before every run, bounds sessions, messages, context, output, retries, and time, and retains content only in memory. The fixed system instruction grants no tools or file, database, shell, plugin, genealogy, or autonomous authority. The bounded source transport and Chat presentation described below consume this service; target-matched packaged network evidence remains a later gate.
  • The LLM service now includes an internal asynchronous adapter for authorized provider streams. Consent and capability checks precede its provider worker; bounded queue and chunk sizes, an absolute deadline, and cooperative cancellation constrain execution. Success, failure, timeout, and cancellation record exactly one privacy-minimal audit result. Structured responses retain the validated non-streaming path, and this source work adds no API, Electron, renderer, or public streaming surface.
  • The 0.6.0 source-level private chat transport exposes fixed authenticated stream-start, SSE, and cancellation routes through an Electron-Main-owned source bridge. Main validates owner and monotonic lifecycle events, batches for at most 16 milliseconds or 4 KiB, pauses above 256 KiB of exact unacknowledged UTF-8 JSON bytes, cancels after a 15-second renderer stall, and permits only one same-run cursor reconnect without retrying provider output. Completion, cancellation, failure, shutdown, and restart reconciliation emit one payload-free terminal audit result. The renderer Chat destination now consumes that transport with ordered owner-scoped state, explicit provider and privacy selectors, safe Markdown presentation, plain-text copy, and Main-confirmed external HTTPS links. Target-matched packaged adversarial evidence remains #131.
  • The 0.6.0 desktop source presents a versioned, allowlisted schema for five non-secret settings with optimistic revisions and atomic owner-only publication. Its fixed bridge also provides status, set, and verified-delete credential operations while keeping values write-only in the Python OS keyring boundary. Environment-managed credentials remain read-only, and the renderer retains status rather than secret input. Packaged-runtime evidence for these new methods remains part of the Issue #131 desktop gate.
  • The 0.6.0 desktop renderer source uses a reusable responsive application shell with typed navigation, capability-gate, seven-state async, coded-error, and dialog-focus contracts. Persistent local/offline status, a keyboard destination palette, deterministic skip and focus behavior, exact-lock Chromium accessibility scans, and minimum-window 200% zoom coverage establish source-level presentation evidence without adding IPC, network, filesystem, provider, consent, or domain authority. Target-matched screen-reader and packaged accessibility evidence remains part of Issue #131.
  • First-run desktop onboarding now recommends the only available mode, Local Desktop, while keeping Connect Remote and Host Remote visibly advanced and unavailable. A typed startup report checks configuration, SQLCipher, keyring, and workspace readiness without exposing secrets, paths, records, prompts, or host identity. Blocking failures preserve a read-only recovery shell; one bounded retry only rechecks state and cannot initialize a database, overwrite a key, fall back to plaintext, or open a listener. Packaged desktop secret access is keyring-only, while the documented CLI/headless environment fallback remains unchanged.
  • A schema-v1 deployment-profile control plane now makes Local Desktop the explicit safe default and exposes reviewed copy, previews, confirmation-bound local recovery, diagnostics, and redacted backup/support metadata through the canonical CLI/service boundary. It never discovers a server, opens or widens a listener, starts a container, or moves genealogy data. Connect Remote and Host Remote remain visibly advanced but fail closed until their separate enrollment and host-runtime work ships.
  • Electron Main now contains a schema-v1 host container-control foundation for later Local Desktop and Host Remote application work. It verifies an app-owned Unix endpoint and Engine identity, ignores ambient Docker selection, validates an exact hardened Compose plan, runs bounded no-shell lifecycle commands, and reconciles only exactly labeled resources. Native macOS arm64 evidence exercises its isolated Colima lifecycle and cleanup without changing the default engine. No Docker authority crosses to preload, renderer, or containers.
  • Issue #348 adds explicit status, review, and apply workflows for acquiring and managing the macOS arm64 local-runtime substrate. A packaged schema-v1 policy binds Colima, Lima, Docker CLI, Compose, Buildx, and the VM image to exact versions, assets, byte lengths, SHA-256 values, and license identities. Setup requires Apple silicon, macOS 13 or later, hardware virtualization, and 24 GiB free; it uses an app-owned profile and context without administrator privileges or ambient Docker selection. Settings and equivalent one-JSON-line commands support setup, start, stop, repair, preserve-data removal, explicit delete-data removal, resumable partial downloads, and verified offline reuse. This does not start an AncestryLLM application container, activate a deployment profile, mount genealogy data, or make Docker Desktop mandatory.
  • Diátaxis information architecture applied to the documentation navigation and Home.md, with clear Diátaxis mode headings in the sidebar.
  • Page-level SEO metadata sidecar (docs/_data/page_metadata.json) injected into the Pages staging tree; Wiki output remains front-matter free.
  • jekyll-seo-tag and jekyll-sitemap enabled in the Pages build.
  • robots.txt published to the documentation site.
  • GitHub Pages workflow upgraded to upload-pages-artifact v5, which uses the repository-pinned upload-artifact v7 internally.
  • docs/DOCS_AUTHORING.md authoring rules, Diátaxis migration inventory, and editorial baseline added.
  • Four fictional, provider-none Electron and terminal screenshots are embedded in their owning desktop, CLI, console, and v0.6 learning-path pages. One manifest drives transactional regeneration and exact, nonmutating CI drift checks; failure artifacts contain only sanitized scenario and SHA-256 data.
  • Reference and Explanation pages now live under the classified docs/reference/ and docs/explanation/ paths with Git history preserved. GitHub Wiki basenames remain stable, Pages routes intentionally follow the classification, and the executable OpenAPI document remains at docs/api/openapi-v1.json.
  • make docs-cutover now composes the canonical source, Pages, flat-Wiki, and external-link exception contracts into one offline exact-head gate. It proves clean committed publishing inputs, repeatable Pages and Wiki output, and idempotent Wiki synchronization without replacing post-merge hosted publication evidence.
  • ADR-0026 records the accepted local-container and advanced remote deployment architecture, ownership model, quantitative budgets, and threat-model gates. The profile control plane and host-only control foundation described above are implemented, but no container or remote application runtime support is added in this release.
  • docs/release-evidence/0.6.0/ evidence directory added.
  • Repository setup, CI, release-readiness, release, desktop-sidecar, and release-project proof jobs verify the pinned uv 0.12.1 release archive, executable hash, and GitHub provenance before first execution.
  • Sanitized schema-v1 bootstrap receipts are retained by CI and are required by release evidence; stock-pip wheel and sdist consumer smoke tests remain.
  • The former dev extra is replaced by locked PEP 735 groups for linting, typing, tests, security, builds, and release verification. Purpose-specific CI jobs synchronize only their declared profiles; provider and desktop extras retain their user-facing installation meaning.
  • Repository environment ownership is centralized in Make and exact uv 0.12.1 commands. A system Python 3.12-3.14 is required, .python-version selects 3.12 by default, and uv cannot download another interpreter.
  • Exact ty 0.0.69 runs visibly beside strict mypy as a nonblocking advisory. Its complete-tree diagnostics, parity fixtures, timings, and suppressions are recorded in the ty advisory evaluation; strict mypy and pydantic.mypy remain the authoritative 0.6 release gate.
  • Ruff remains at 0.16.1 while reviewed typing, performance, modernization, and correctness rule families are enabled in separate batches. Provider-import, Pydantic-runtime, GEDCOM characterization, and startup evidence are recorded in the Ruff rule-expansion evaluation.
  • A locked uv_build 0.12 candidate is evaluated reproducibly beside the unchanged production setuptools backend. Candidate outputs are internally reproducible but fail artifact equivalence because of source, license, metadata, and wheel-record drift, so adoption is rejected/deferred; the complete result is in the uv_build evaluation.
  • Isolated user installation now supports uv tool install ancestryllm alongside the retained pipx and ordinary pip consumer paths.
  • Exact-commit upstream Ruff and uv hooks replace the former local wrappers, while local gitleaks and canonical pre-push gates remain. The complete dependency audit proves parity between uv export --locked --all-extras --all-groups and uv.lock, and every tracked Markdown file receives the same GFM validation.
  • Checked-in VS Code settings use Ruff for linting and formatting without unsafe fixes. Because the 0.6 ty evaluation did not pass every cutover gate, mypy editor ownership and strict pydantic.mypy checking remain authoritative.
  • The desktop dependency gate replaces the vulnerable extract-zip Electron installer helper with exact Electron-maintained @electron-internal/extract-zip 1.0.5, a lock-digested compatibility patch, and a canonical frozen install that rebuilds and verifies the active Electron runtime for desktop verification and release workflows. The frozen dependency graph also pins patched fast-uri 3.1.6, js-yaml 4.3.2, and @xmldom/xmldom 0.8.15 to clear the high-severity dependency gate.

Documentation

Upgrade notes

Developer and release tooling now uses the verified repository-local uv bootstrap and purpose-specific locked groups. Contributors must install a supported system Python and run make setup; the repository will not download Python or accept a different uv, and the former .[dev] installation path is no longer supported. No genealogy, storage, or public consumer API contract has changed. The private loopback API adds the fixed synchronous and streaming transient-chat operations described above. The fixed Electron source bridge owns transport and backpressure, and the bounded Chat destination consumes only that bridge. The CLI adds the deployment command family for profile copy, status, preview, explicit local recovery, diagnostics, and redacted evidence. The packaged desktop executable adds a separate --local-runtime status/preview/apply interface for macOS arm64 runtime lifecycle automation. The private loopback API and fixed Electron bridge add the versioned settings and write-only credential-management operations described above; packaged Electron sidecar startup and shutdown are hardened as described above.

Project-produced 0.x binaries remain unsigned. The sidecar manifest detects payload substitution relative to the built Electron main process; it is not a publisher signature or whole-application protection. Issue #132 owns publisher signing and notarization for v1.0.0. Verification and process spawn remain separate filesystem operations, leaving a narrow local time-of-check/time-of-use replacement residual. The macOS CI verification overlay preserves the exact manifested payload bytes by excluding only the sidecar resource tree from Electron’s second ad hoc signing pass; PyInstaller’s nested signatures remain intact and the outer application signature still seals the resource tree.

GEDCOM content and format contracts are unchanged; publication now uses the shared durable mutation boundary described above. Application-container and remote-hosting behavior is unchanged. The source-level Electron Chat destination is a presentation-only consumer of fixed bridge methods: it adds no direct renderer network, tool, file, database, genealogy, or persistent-storage authority. Chat execution accepts only an exact stored profile and model and requires the existing endpoint, credential, policy, and consent checks before every provider call. Selecting a default-provider setting neither activates a provider nor grants cloud consent. Deployment profile selection is now an implemented fail-closed control-plane constraint; the host supervisor and Issue #348 runtime manager acquire and manage only the local Docker substrate. They are not an application-container or remote-runtime availability claim.

Interoperability limitations

RootsMagic, Ancestry, Geni, and MyHeritage interoperability is unverified for 0.6.0 because no dated fictional-data manual import evidence is recorded. This release does not make a positive compatibility claim for an unverified vendor. Automated tests verify standards-based GEDCOM formatting, deterministic loss-minimal preservation, and immutable RootsMagic handling only.

Installation and verification

Install the isolated CLI application with either supported tool:

uv tool install ancestryllm==0.6.0
pipx install ancestryllm==0.6.0

Ordinary pip install ancestryllm==0.6.0 remains supported for consumers who manage their own environment. Verify the public version with ancestry --version; it returns ancestry 0.6.0.

Download desktop installers only from the immutable GitHub Release. The release also contains the wheel, source distribution, full SHA256SUMS, CycloneDX SBOMs, binary-signing disclosure, artifact manifest, security and interoperability evidence, and provenance attestations. Verify downloads from their directory with:

shasum -a 256 -c SHA256SUMS

SHA256SUMS intentionally omits only itself. Published artifacts and the v0.6.0 tag are immutable; a correction requires a new version.