your-local-cost-explorer 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# 0.4.0 - Your Local Cost Explorer
+
+- Rename the public project and npm command to `your-local-cost-explorer`. Keep the existing private data/runtime directory so upgrading does not lose saved work.
+- Keep the local light design and sidebar. Remove Data Sources navigation; upload and retained-file controls appear only on Dashboard. Replace broken dash characters with `-`.
+- Inspect observed CUR dates locally for CSV, gzip and Parquet. Offer supported 7/30/90/180-day windows ending at the supplied data's latest date, with earlier rows as baseline. Missing history stays unavailable.
+- Put previous-check and device-file comparisons below the baseline fields. Retained comparisons verify original file hashes and cannot contaminate primary data.
+- Preserve all eight detectors, exact decimal financial calculations, commitments, allocation, settings and downloadable local reports. No hosted or automatic connections are included.
+
+Focused verification: real loopback uploads, CUR date aliases/formats/conflicts, calendar windows, previous-check provenance and separation, DOM upload/period/button behavior, small independent signed-charge/rounding ledger, duplicate removal, original eight-detector and commitment controls, hosted pricing withdrawal tests, frontend typecheck and production build. No large-file laptop stress test.

package/DESIGN.md

@@ -0,0 +1,9 @@
+# Local manual dashboard
+
+The local edition keeps its own light workspace, white sidebar, slate text (#263445), blue controls (#4165cf) and rectangular cards. It deliberately does not reuse the main app's dark Flow palette, horizontal navigation or pill-shaped toolbar.
+
+The main app supplies button labels and page responsibilities: Dashboard, Check Charges, Findings, Commitments, Allocation, Reports and Settings. Billing files live only on the Dashboard. Manual behavior includes evidence, file-anchored date presets, explicit comparisons, local review statuses/notes, archive/restore, named report snapshots and general/team preferences. Connections, authentication, billing and automatic workflows are absent.
+
+Settings support company name, default date range, detector sensitivity, team CRUD, documentation and hardware visibility. Check snapshots preserve the settings/mappings used at calculation time. Reports never send automatically.
+
+Original HTML/CSS/JS is bundled without CDN assets or copied library code. Earlier Forge, Magic UI and Uiverse reference queries inform accessible native control patterns only. Device-derived budgets replace fixed input-size caps; no hardware capacity claim is made for arbitrary files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CommitOps contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MANUAL-FEATURES.md

@@ -0,0 +1,21 @@
+# Manual-only feature map
+
+| Main app manual area | Local equivalent |
+|---|---|
+| Dashboard and check selection | Independent light dashboard, saved-check picker, observed monthly spending/usage and explicit limitations |
+| Check Charges | Local CUR1/CUR2 CSV/gzip/Parquet, multiple primary and explicit comparison files, date windows, expectations, manual run/cancel |
+| Eight detectors and source evidence | Same extracted engine; evidence drawer, source hashes and complete JSON |
+| Findings filters and review workflow | Search, severity/detector/status filters, bounded pages, local notes/statuses, archive/restore |
+| Commitments | Savings Plan/RI summaries, consumed/unused amounts and missing inventory reasons |
+| Allocation and team ownership | Category/account consumption and local account/team mapping snapshots |
+| Reports | Explicit whole-check JSON, readable meeting HTML, CSV and print; no sending |
+| Dashboard billing files and history | Retained upload identities, explicit removal, keyset history pagination, check archive/restore |
+| Baselines and previous consumption | File-anchored 7/30/90/180-day choices, retained-check/device baselines, canonical usage comparison and observed daily history |
+| General & teams settings | Persisted company name, default date range and creep sensitivity; team add/edit/delete; documentation and hardware budgets |
+| Saved reports | Generate, rename, archive/restore, download and delete immutable local report snapshots |
+| Connections/account billing/automatic settings | Not included; no hosted login, quotas, billing or provider integration |
+| Schedules, rules and automatic delivery | Absent from both runtime routes and UI; not merely hidden |
+
+No claims of company/revenue growth or unsupported multi-check total aggregation are introduced. To analyse a wider scope, select its canonical source files in a new permitted manual check rather than adding overlapping saved result totals.
+
+No fixed file-size or batch-byte caps apply to this local edition. Processing budgets derive from available hardware, with OS headroom and explicit resource-failure reporting.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# Your Local Cost Explorer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local-only AWS billing dashboard, with its own light dashboard design and sidebar navigation. Upload CUR CSV, CSV.gz or Parquet exports and review reported charges, all eight detectors, commitment consumption, allocation and supporting evidence on your device.
+
+## Install from npm
+
+Install Node.js 20+ with npm, then:
+
+```sh
+npm install -g your-local-cost-explorer
+your-local-cost-explorer
+```
+
+The package's install step automatically provisions a private Python 3.12 runtime and all pinned analysis dependencies. Python, pip, DuckDB and Arrow do not need separate installation. It downloads a pinned, SHA256-verified Astral uv binary and uses it to install managed Python and public PyPI wheels. Supported platforms: Windows, macOS and Linux (glibc), x64 and ARM64. Installation requires internet and sufficient free disk space. Node/npm are prerequisites because npm itself runs the installer; no administrator permissions are needed.
+
+The first launch also checks setup, so environments that skip npm lifecycle scripts can recover automatically. To retry an interrupted installation:
+
+```sh
+your-local-cost-explorer --setup
+```
+
+Setup never opens or analyses billing files. Subsequent launches work offline after successful installation; ordinary analysis disables outbound Python sockets and DuckDB remote extension loading. Dependencies and runtime tools live privately under your user data directory, not inside the downloaded package. Installation does not change system Python or global PATH.
+
+Open the printed `http://127.0.0.1:8080/#token=...` URL. Keep the launch token private. Use `your-local-cost-explorer --port 8081` if 8080 is busy. `your-local-cost-explorer --help` does not download or start anything.
+
+## Install from GitHub
+
+```sh
+git clone https://github.com/leejan2647-a11y/your-local-cost-explorer.git
+cd your-local-cost-explorer
+npm install
+npm start
+```
+
+`npm install` provisions the runtime automatically, just like the npm package. No Python or separate setup command is required. A GitHub archive works too: extract it, run `npm install`, then `npm start`.
+
+## Manual workflow
+
+1. **Dashboard billing files → Check Charges:** upload primary files on the Dashboard. The app detects their observed usage-date bounds and offers supported last 7, 30, 90 or 180 days ending at the latest supplied date. All earlier rows form the baseline. A 30-day export offers 7 and 30 days; selecting all 30 leaves no historical baseline. Bounds do not prove complete coverage. Choose manual dates when needed, optional service expectations, then run or cancel a check. Below the baseline dates, choose earlier rows, retained files from a previous completed check, or comparison files from your device. Comparison files stay separate; missing or changed retained sources are refused.
+2. **Dashboard:** view reported charges, canonical observations, coverage, monthly observations and supported usage comparisons for a selected saved check.
+3. **Findings:** search/filter by service/account/text, severity, detector and review status; inspect billing-row evidence; save local notes/statuses; archive and restore findings. Review annotations never rewrite calculated financial evidence.
+4. **Commitments:** review Savings Plans/reserved instances, purchased/used/unused amounts and inventory limitations.
+5. **Allocation and team mappings:** view supported category/account consumption, map 12-digit AWS account IDs to local teams, and preserve the mapping snapshot used by each result. Run a new manual check to apply changed mappings to new results.
+6. **Reports:** generate named snapshots from one or several completed checks, rename/archive/restore/download/delete saved reports, download complete JSON, a readable standalone meeting HTML report or findings CSV, or print locally. Multiple check snapshots remain separate; totals are never added together. Whole-check reports are distinct from filtered findings views. CSV text is protected against spreadsheet formula interpretation.
+7. **Dashboard billing files:** select retained file identities, inspect names/bytes/roles/hashes, remove files explicitly, and preserve already saved result evidence.
+8. **Check history & evidence:** page through all saved runs, select previous results, archive/restore checks, review original evidence and baselines. Archived does not mean deleted.
+
+All eight detector IDs are included: `unexpected-charge`, `spike`, `gradual-creep`, `new-charge`, `usage-cost-mismatch`, `marketplace`, `expectation-mismatch` and `unused-commitment`. Relevant optional columns, usable history and expectations are required for their corresponding measurements. Unsupported evidence is unavailable, never a fabricated clean assessment.
+
+**There is no automatic path.** No schedules, rules, background discovery, AWS connections, hosted authentication, saved delivery connections, email or webhook sending, payment services, telemetry or hosted API clients are included. Check execution uses a local child process only after the user clicks Run. Progress polling observes that manually requested work; it cannot start another check. Reports are local files, as explicitly requested by the owner.
+
+## Financial meaning
+
+Estimates use only the AWS data provided. Changes in cloud usage do not establish company or revenue growth. Missing exports, workload changes, discounts and billing adjustments can affect the result.
+
+Spending is reported AWS charges, not an independently reconciled final invoice. Finding impacts can overlap and must not be summed into a bill total. Monthly usage comparisons preserve coverage, currency, unit and compatible-basket requirements. Missing days remain unknown. Partial/open months never become completed-month growth just because time passes. Mixed quantities are not added. The existing exact decimal/canonical financial engine is reused.
+
+## Storage and safeguards
+
+User data lives in `%LOCALAPPDATA%/commitops-local/data` on Windows or `~/.local/share/commitops-local/data` on Linux/macOS. Runtime dependencies live in an isolated `runtime-v2-<dependency fingerprint>` folder, managed Python in `python`, and verified uv in `tools`. Direct Python launch supports an explicitly chosen `--data` directory. Browser requests accept stored upload IDs, never arbitrary filesystem paths or remote URLs.
+
+The app binds only to `127.0.0.1`, validates Host/Origin and requires a random launch token for data access. A lifetime data-directory lease prevents two instances from damaging each other's work. Uploads are streamed; one analysis runs at a time; cancellation kills its child process without saving incomplete results as completed. SQLite transactions close their connections deterministically, including on Windows.
+
+There are no fixed per-file or combined-check byte caps and no commercial quotas in the local edition. Your device's available hardware determines what it can process. The app uses all available CPU threads (respecting affinity/container quotas), allows DuckDB to use up to 70% of currently available RAM, and derives spill space from the working disk's current free space. It reserves proportional memory/disk headroom for Python, the operating system and other applications. One manually requested analysis uses this shared budget at a time.
+
+CPU settings permit parallel work where the engine supports it; some stages remain serial. The Settings page shows current resource budgets. Device pressure or memory/disk exhaustion produces an explicit unavailable/interrupted outcome rather than a completed financial result. The app does not close other programs or promise that every file will complete. Decompression, column widths, group cardinality and other running programs affect requirements. Supported data formats and financial-evidence validity rules still apply regardless of file size. Users are responsible for their device, power and cooling.
+
+To use another drive with more free space, choose trusted local directories at launch:
+
+```sh
+your-local-cost-explorer --data D:/CommitOpsData --work-dir D:/CommitOpsWork
+```
+
+`--data` selects the retained-data directory; existing saved data remains in its original directory until you intentionally migrate it while the app is stopped. `--work-dir` selects disposable processing storage. The browser cannot submit filesystem paths.
+
+Stop the app before deliberately removing its data directory to clear all retained results/mappings. Save needed reports first. Removing individual retained files never deletes saved financial results. Local same-user malware and someone with device access are outside launch-token protection.
+
+## Source and tests
+
+`SOURCE-INVENTORY.json` records the allowlisted original financial modules and export hashes. `MANUAL-FEATURES.md` maps the local manual experience. Only intended financial code and local adapters are exported; no hosted repository history, private environments, user records, keys or provider configuration are included. New dashboards use native bundled HTML/CSS/JS with no remote fonts, scripts or assets.
+
+After a source install, `npm test` runs focused Node tests (Node 22.22.2+ for the development-only jsdom test dependency). Python tests under `tests/` use only synthetic data and temporary local storage. The financial engine has separate earlier parity receipts; unchanged calculations are not re-tested for every stylesheet edit.
+
+MIT licensed. Astral uv is downloaded separately under its upstream MIT/Apache-2.0 terms; managed CPython and installed Python/npm dependencies retain their respective upstream licences. No third-party UI component source was vendored. Forge, Magic UI and Uiverse were consulted as design references; Button names, page responsibilities and manual workflow behavior follow the main application; its palette and visual layout are not copied. No hosted assets or integration code are included.

package/SOURCE-INVENTORY.json

@@ -0,0 +1,127 @@
+[
+  {
+    "file": "app/core/analysis_storage.py",
+    "upstream_sha256": "cb93f0cd05f9e5afb2a29c2379eb1d845bf86606cf458f0960c09e0036a020da",
+    "export_sha256": "d54d25bda088d9e6ac7e3393e2f862e633f1ce7088699bf092eed4e59fca5fa2"
+  },
+  {
+    "file": "app/growth/contracts.py",
+    "upstream_sha256": "069570ae90cf1452542f1d7e1cdf2cafea258f4b68b9c3315ce119784d9363fd",
+    "export_sha256": "f64dc67efc3083fb72bf0b45a6e4ba619a03ff5c26178f06d506fb213d81e30a"
+  },
+  {
+    "file": "app/pipeline/attribution.py",
+    "upstream_sha256": "195f1b604f7c8fc16dc127573cc7450d5b893909dd7277e47b4075e5b9dbdb74",
+    "export_sha256": "195f1b604f7c8fc16dc127573cc7450d5b893909dd7277e47b4075e5b9dbdb74"
+  },
+  {
+    "file": "app/pipeline/baseline.py",
+    "upstream_sha256": "85055663079228a178dcde352faaba6f2f56e07d024b98402938cab4608b4d38",
+    "export_sha256": "7a407fc38d48de2886ca57ac730a15202507942205ccebdd41ce7b2eded128b7"
+  },
+  {
+    "file": "app/pipeline/canonical.py",
+    "upstream_sha256": "226c7502cdb5dd5d3cefe35cd0a447380a5b59b0a50568c4161eb941f7944497",
+    "export_sha256": "a740d00b4d315f698081d87e92b63a41876912d2a9fd6b29f38a9f8827e57aab"
+  },
+  {
+    "file": "app/pipeline/commitments.py",
+    "upstream_sha256": "b63f255ee16b0d159010ffd7222c7a666e241667b3a8c6d32d6a9493246cbc5d",
+    "export_sha256": "b1e62fa369708edb1d8bf1ecffbe3c25828d9ea65efb0c2edd58a084ab0bbfb4"
+  },
+  {
+    "file": "app/pipeline/comparison.py",
+    "upstream_sha256": "2d431a66e842d285e18913412417b1b70318617ccc8598482351848a414bcfc8",
+    "export_sha256": "d729b56860e7d326762376c9aedf95e01b11d2fa96daf62b2e6fcbe11dfa6f84"
+  },
+  {
+    "file": "app/pipeline/creep_policy.py",
+    "upstream_sha256": "0798da2d98b7c073f6362a390e37dd5891048e396188cb2a07493a8be762ed93",
+    "export_sha256": "956aca20469b74f9e8eedb5f5733dbb5638d6d9daadf14ed17054581168fc800"
+  },
+  {
+    "file": "app/pipeline/currency.py",
+    "upstream_sha256": "f11845613be80b99f2c5405955872cb68a7576fa47f0bc0ca5d6d7b7441014ec",
+    "export_sha256": "b3c4a141c095297394727a95576760043c63a4eefda224609d94eccce2bd5612"
+  },
+  {
+    "file": "app/pipeline/detectors.py",
+    "upstream_sha256": "f1ac4e2bd94324acfd4db48011cc544df10506a2fb1daf2912324526a200315f",
+    "export_sha256": "f1ac4e2bd94324acfd4db48011cc544df10506a2fb1daf2912324526a200315f"
+  },
+  {
+    "file": "app/pipeline/evidence.py",
+    "upstream_sha256": "0b7d45dfef68bebb83b3c0b2a90782ee0d2375bc95f5bcf6b336d78cc01bbb31",
+    "export_sha256": "0b7d45dfef68bebb83b3c0b2a90782ee0d2375bc95f5bcf6b336d78cc01bbb31"
+  },
+  {
+    "file": "app/pipeline/finding_amounts.py",
+    "upstream_sha256": "bce0050111c3bf085d6ba5b95596f89299f893a36cd94642121b6f1d57bc1143",
+    "export_sha256": "aa464e4a3901491ed4d576ce34b1df817bbbf1d17545147f41f08daa0d1fcd36"
+  },
+  {
+    "file": "app/pipeline/history_facts.py",
+    "upstream_sha256": "7a77eb3ddeb7bf1b8f29630d71e86ad2dc1bf5fd80c2496f3c66a32abcdebc39",
+    "export_sha256": "85aa2275401cc9c9e74a95c83f5d32c8b35b4fb2b4a7b9739d66cf691e9a664d"
+  },
+  {
+    "file": "app/pipeline/ingest.py",
+    "upstream_sha256": "45becd68afb7c7e4ab044e0a79695e3d23e204e040d687d53179ea159f9da48b",
+    "export_sha256": "d1ab420ce420ac737d01b63ef6fcb85a969f3a8ad58907e497ede5ed9568a54a"
+  },
+  {
+    "file": "app/pipeline/money.py",
+    "upstream_sha256": "6f276ed3e2c6c6b76986b3955207f0b9f3b96080cc2afc7e2547f772a8612837",
+    "export_sha256": "75aa807bbb79e88e22a72ed5861c07c2b84be7ad9db9ae2d57651881bc482ff9"
+  },
+  {
+    "file": "app/pipeline/monthly_growth.py",
+    "upstream_sha256": "41abd5a5aecb15fed6f603dfa0541b794a39aae43f58a99b9abe3805b1516242",
+    "export_sha256": "5b4a7431cca0e5c8dc3e7d1611bacdc2b8a39944c81621158bbcf1d4f25fc6ab"
+  },
+  {
+    "file": "app/pipeline/reserved_instances.py",
+    "upstream_sha256": "73b402e825b81171190ca912e5d313ac3dee07d2a2ea44c1edc4ac1b8a53cd15",
+    "export_sha256": "73b402e825b81171190ca912e5d313ac3dee07d2a2ea44c1edc4ac1b8a53cd15"
+  },
+  {
+    "file": "app/pipeline/routing_tags.py",
+    "upstream_sha256": "dd091c32195ae9543d052922cb7999f5ac5433c00220d3afb5037ded240adc24",
+    "export_sha256": "b0e27623f371a6ee153a9fb1fc8bbb5dad8615c1bc9d84114cbed524f2ea8ca6"
+  },
+  {
+    "file": "app/pipeline/run.py",
+    "upstream_sha256": "1a03edbfd4d3de72422b50d7405ae99e04f74d59709afd0ebb3c6f0f50feb06e",
+    "export_sha256": "4302c7778b6a4ab88cccf19d0d7800fa7adfb2302027b3b23c3cb59912d7bb8e"
+  },
+  {
+    "file": "app/pipeline/savings_plans.py",
+    "upstream_sha256": "742ee44de6372bcf8fe700a2b75c4f5a6aae1dc44ac2235bd3fe89946135067f",
+    "export_sha256": "742ee44de6372bcf8fe700a2b75c4f5a6aae1dc44ac2235bd3fe89946135067f"
+  },
+  {
+    "file": "app/pipeline/spend_history.py",
+    "upstream_sha256": "92df5bfbd084172f0664e089438b1f785df89fa1b98e3ad2378faa14f7504727",
+    "export_sha256": "fc56f38c0bc838c56ebc7a298d4eaaa842ee8a9860c2d740d306f5cc3f4aa74d"
+  },
+  {
+    "file": "app/pipeline/string_source.py",
+    "upstream_sha256": "14663adf0fbebd87470e92f8fce3f5fea17d13a6292b0b8bbf0da8350fdf8d51",
+    "export_sha256": "4658e9808fa2d00c0aa826ce0b6e9421420bc57240d42d3425bf4b8f6f7a52c3"
+  },
+  {
+    "file": "app/pipeline/types.py",
+    "upstream_sha256": "ac19856a1fd053c604fa50fa5db880c33694eb93f8f346e35696f2c572b2a5af",
+    "export_sha256": "ac19856a1fd053c604fa50fa5db880c33694eb93f8f346e35696f2c572b2a5af"
+  },
+  {
+    "file": "app/pipeline/validate.py",
+    "upstream_sha256": "fe77eaffc5c791455c78fd0d4f0a533784bed9744543363525e3b1f0a548c5ed",
+    "export_sha256": "6ca62ffe3ea2bf4e8312ba5be42283408f5e9b197d0fad1b4b82d35014404c4b"
+  },
+  {
+    "file": "app/services/monthly_growth.py",
+    "upstream_sha256": "f7710949294198a259ebd0611c3ced5b5cae4a56a0ca73b8781976faf28f484a",
+    "export_sha256": "fcc968904c28b3d00809bc8655f87cb3c081b7527fc590b154fcff8ee78d376c"
+  }
+]

package/bin/commitops-local.cjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+'use strict';
+const {spawn}=require('node:child_process');
+const path=require('node:path');
+const {setup}=require('./runtime.cjs');
+const root=path.resolve(__dirname,'..');const args=process.argv.slice(2);
+if(args.includes('--help')){console.log('your-local-cost-explorer [--port 8080] [--setup]\nFirst installation provisions a private Python runtime. Analysis stays offline.');process.exit(0);}
+async function main(){
+ const info=await setup(root);
+ if(args.includes('--setup')){console.log('Setup complete. Run your-local-cost-explorer.');return;}
+ const env={};
+ for(const key of ['PATH','SystemRoot','WINDIR','TEMP','TMP','TMPDIR','HOME','USERPROFILE','LOCALAPPDATA','LANG'])if(process.env[key])env[key]=process.env[key];
+ env.PYTHONNOUSERSITE='1';env.PYTHONDONTWRITEBYTECODE='1';
+ const child=spawn(info.python,[path.join(root,'engine','local_app.py'),'--data',path.join(info.home,'data'),...args],{stdio:'inherit',shell:false,env});
+ child.on('error',error=>{console.error(error.message);process.exitCode=1;});child.on('exit',code=>{process.exitCode=code||0;});
+ for(const signal of ['SIGINT','SIGTERM'])process.on(signal,()=>child.kill(signal));
+}
+main().catch(error=>{console.error(error.message);process.exitCode=1;});

package/bin/runtime.cjs

@@ -0,0 +1,81 @@
+'use strict';
+const fs=require('node:fs'), path=require('node:path'), os=require('node:os'), crypto=require('node:crypto'), zlib=require('node:zlib');
+const {spawnSync}=require('node:child_process');
+const VERSION='0.13.5';
+const ASSETS={
+ 'win32-x64':['uv-x86_64-pc-windows-msvc.zip','a38b8d1902b7cfbc76b423ba1bb456f623f42064cdc72628b6075b89afd1019a'],
+ 'win32-arm64':['uv-aarch64-pc-windows-msvc.zip','09f47edf90726084a70f9426f6e3ca4f46e9bf7cbf23b1716ec64d60b055fae3'],
+ 'linux-x64':['uv-x86_64-unknown-linux-gnu.tar.gz','f68d291c75783122dad58ab77def0e13f3233f358731db5d6d7e8715603b928f'],
+ 'linux-arm64':['uv-aarch64-unknown-linux-gnu.tar.gz','4bb69cf95ed13f23713bb7bc09f241896ea0c75b7c557e615a20604b82f9c403'],
+ 'darwin-x64':['uv-x86_64-apple-darwin.tar.gz','b0f52b0e3945b4107d89024ea38e625683011fbfc05a0d98f9fa2d6dcee28c66'],
+ 'darwin-arm64':['uv-aarch64-apple-darwin.tar.gz','743f85035a1996ecb350659e01cd9faea9709829be09b1b4b03c73eaf3c9cd73']
+};
+function locations(root){
+ const home=path.join(process.env.LOCALAPPDATA || path.join(os.homedir(),'.local','share'),'commitops-local');
+ const fingerprint=crypto.createHash('sha256').update(fs.readFileSync(path.join(root,'requirements.txt'))).update('managed-python-3.12-v2').digest('hex');
+ const runtime=path.join(home,'runtime-v2-'+fingerprint.slice(0,16));
+ return {home,runtime,python:path.join(runtime,process.platform==='win32'?'Scripts/python.exe':'bin/python'),marker:path.join(runtime,'.ready'),fingerprint};
+}
+function ready(info){return fs.existsSync(info.python)&&fs.existsSync(info.marker)&&fs.readFileSync(info.marker,'utf8')===info.fingerprint;}
+function binaryFromTar(archive){
+ const tar=zlib.gunzipSync(archive,{maxOutputLength:200*1024*1024});
+ for(let offset=0;offset+512<=tar.length;){
+  const header=tar.subarray(offset,offset+512),name=header.subarray(0,100).toString().split('\0')[0];
+  if(!name)break;
+  const size=parseInt(header.subarray(124,136).toString().replace(/\0/g,'').trim(),8);
+  if(!Number.isSafeInteger(size)||size<0||offset+512+size>tar.length)throw Error('Invalid runtime archive');
+  if(path.posix.basename(name)==='uv'&&[0,48].includes(header[156]))return tar.subarray(offset+512,offset+512+size);
+  offset+=512+Math.ceil(size/512)*512;
+ }
+ throw Error('Runtime binary missing from archive');
+}
+async function uvBinary(info){
+ const spec=ASSETS[process.platform+'-'+process.arch];
+ if(!spec)throw Error('Automatic installation supports Windows/macOS/Linux x64 and ARM64. This platform is unsupported.');
+ const folder=path.join(info.home,'tools',VERSION),binary=path.join(folder,process.platform==='win32'?'uv.exe':'uv'),stamp=binary+'.sha256';
+ if(fs.existsSync(binary)&&fs.existsSync(stamp)&&crypto.createHash('sha256').update(fs.readFileSync(binary)).digest('hex')===fs.readFileSync(stamp,'utf8'))return binary;
+ console.log('Downloading verified local runtime installer…');
+ const response=await fetch(`https://github.com/astral-sh/uv/releases/download/${VERSION}/${spec[0]}`,{signal:AbortSignal.timeout(120000)});
+ if(!response.ok)throw Error('Runtime download failed: HTTP '+response.status);
+ const chunks=[];let size=0;
+ for await(const chunk of response.body){size+=chunk.length;if(size>50*1024*1024)throw Error('Runtime archive exceeds expected size');chunks.push(chunk);}
+ const archive=Buffer.concat(chunks);
+ if(crypto.createHash('sha256').update(archive).digest('hex')!==spec[1])throw Error('Runtime download checksum mismatch');
+ let contents;
+ if(spec[0].endsWith('.zip')){
+  const {unzipSync}=require('fflate');const files=unzipSync(archive,{filter:entry=>entry.name.split('/').pop()==='uv.exe'&&entry.originalSize<100*1024*1024});
+  contents=Object.entries(files).find(([name])=>name.split('/').pop()==='uv.exe')?.[1];
+ }else contents=binaryFromTar(archive);
+ if(!contents?.length)throw Error('Runtime binary missing');
+ fs.mkdirSync(folder,{recursive:true,mode:0o700});const temporary=binary+'.'+process.pid+'.tmp';fs.writeFileSync(temporary,contents,{mode:0o700});fs.renameSync(temporary,binary);
+ fs.writeFileSync(stamp,crypto.createHash('sha256').update(contents).digest('hex'),{mode:0o600});return binary;
+}
+async function setup(root){
+ const info=locations(root);if(ready(info))return info;
+ fs.mkdirSync(info.home,{recursive:true,mode:0o700});const lock=path.join(info.home,'.setup-lock');
+ // Exclusive lock file: another install must finish rather than sharing a partial runtime.
+ let handle;
+ try{handle=fs.openSync(lock,'wx',0o600);fs.writeSync(handle,String(process.pid));}
+ catch(error){
+  if(error.code!=='EEXIST')throw error;
+  const pid=Number(fs.readFileSync(lock,'utf8'));let alive=true;try{process.kill(pid,0);}catch(e){if(e.code==='ESRCH')alive=false;}
+  if(!alive){fs.unlinkSync(lock);return setup(root);}
+  for(let i=0;i<240;i++){await new Promise(resolve=>setTimeout(resolve,1000));if(ready(info))return info;if(!fs.existsSync(lock))return setup(root);}
+  throw Error('Another runtime setup is still running. Retry after it finishes.');
+ }
+ try{
+  if(ready(info))return info;
+  const uv=await uvBinary(info);
+  const env={...process.env,UV_PYTHON_INSTALL_DIR:path.join(info.home,'python'),UV_NO_CONFIG:'1',UV_PYTHON_DOWNLOADS:'automatic'};
+  console.log('Installing private Python 3.12 and analysis dependencies. Billing files are not accessed.');
+  for(const args of [['venv','--python','3.12','--managed-python','--allow-existing',info.runtime],['pip','install','--python',info.python,'--only-binary',':all:','--index-url','https://pypi.org/simple','-r',path.join(root,'requirements.txt')]]){
+   const result=spawnSync(uv,args,{env,stdio:'inherit',shell:false,timeout:600000});
+   if(result.error||result.status!==0)throw Error('Runtime setup failed. Check internet access and disk space, then run commitops-local --setup to retry.');
+  }
+  const probe=spawnSync(info.python,['-c','import duckdb,pydantic,pyarrow,pytz,dateutil,psutil'],{env,stdio:'inherit',timeout:30000});
+  if(probe.error||probe.status!==0)throw Error('Installed analysis dependencies did not pass verification');
+  fs.writeFileSync(info.marker,info.fingerprint,{mode:0o600});return info;
+ }finally{fs.closeSync(handle);fs.unlinkSync(lock);}
+}
+module.exports={locations,ready,binaryFromTar,setup,ASSETS};
+if(require.main===module)setup(path.resolve(__dirname,'..')).then(()=>console.log('Local runtime ready.')).catch(error=>{console.error(error.message);process.exitCode=1;});

package/engine/app/core/analysis_storage.py

@@ -0,0 +1,245 @@
+"""Private, disposable working storage for one DuckDB analysis.
+
+Source uploads remain in their retained storage. Only reproducible processing
+files use the operating system's temporary volume.
+"""
+from tempfile import TemporaryDirectory, gettempdir
+from pathlib import Path
+from contextlib import contextmanager
+import os
+import shutil
+import stat
+import threading
+from duckdb import ConnectionException, Error as DuckDBError
+
+
+
+class AnalysisStorageError(OSError):
+    """Processing storage failed, independently of provider export validity."""
+
+
+def _lock(handle, *, blocking=True):
+    if os.name == 'nt':
+        import msvcrt
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK if blocking else msvcrt.LK_NBLCK, 1)
+    else:
+        import fcntl
+        fcntl.flock(handle, fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB))
+
+
+@contextmanager
+def _root_lock(root):
+    root.mkdir(mode=0o700, parents=True, exist_ok=True)
+    info=root.lstat()
+    if not stat.S_ISDIR(info.st_mode) or (hasattr(os,'getuid') and info.st_uid != os.getuid()):
+        raise OSError('Private analysis working storage is unavailable')
+    if os.name != 'nt' and stat.S_IMODE(info.st_mode) & 0o077:
+        raise OSError('Private analysis working storage permissions are unsafe')
+    # Root ownership/mode prevent substitution of this lock or job leases.
+    with (root/'.lock').open('a+b') as handle:
+        if handle.tell()==0:
+            handle.write(b'0');handle.flush()
+        _lock(handle)
+        yield
+
+
+def _reap_locked(root):
+    for directory in root.glob('job-*'):
+        if directory.is_symlink() or not directory.is_dir():
+            continue
+        lease=directory/'.lease'
+        if not lease.exists():
+            # Initialization also holds the root lock. An empty directory
+            # without a lease can only be an interrupted pre-database setup.
+            try:
+                directory.rmdir()
+            except OSError:
+                pass  # Preserve any unrecognized, nonempty directory.
+            continue
+        if lease.is_symlink() or not lease.is_file():
+            continue
+        try:
+            with lease.open('r+b') as handle:
+                _lock(handle, blocking=False)
+                # A worker holding this lease cannot be reaped, including
+                # workers in a different PID namespace. The OS releases it on
+                # timeout/SIGKILL without relying on a Python finally block.
+                if os.name != 'nt':
+                    shutil.rmtree(directory)
+            if os.name == 'nt':
+                shutil.rmtree(directory)
+        except (OSError, PermissionError):
+            continue
+
+
+def reap_orphans(root):
+    with _root_lock(root):
+        _reap_locked(root)
+
+
+class AnalysisConnection:
+    def __init__(self, connection, working, lease, *, disk_reserve=0, memory_reserve=0):
+        self._connection = connection
+        self._working = working
+        self._lease = lease
+        self._stop = threading.Event()
+        self._storage_failed = False
+        self._closed = False
+        self._disk_reserve = disk_reserve
+        self._memory_reserve = memory_reserve
+        self._cursors = set()
+        self._cursor_lock = threading.Lock()
+        self._monitor = threading.Thread(target=self._watch_storage, name='analysis-storage-guard', daemon=True)
+        self._monitor.start()
+
+    def _watch_storage(self):
+        while not self._stop.wait(1):
+            try:
+                free = shutil.disk_usage(self._working.name).free
+            except OSError:
+                free = 0
+            if self._stop.is_set():
+                return
+            from local_hardware import memory
+            available, _ = memory()
+            if free < self._disk_reserve or available < self._memory_reserve//2:
+                self._storage_failed = True
+                with self._cursor_lock:
+                    connections = [self._connection, *self._cursors]
+                for connection in connections:
+                    try:
+                        connection.interrupt()
+                    except DuckDBError:
+                        pass  # A cursor may have closed after the snapshot.
+                return
+
+    def _ensure_available(self):
+        if self._closed:
+            raise ConnectionException('Analysis connection is closed')
+        if self._storage_failed:
+            raise AnalysisStorageError('Your device has insufficient available memory or working disk to continue safely')
+
+    def _new_cursor(self, source):
+        with self._cursor_lock:
+            self._ensure_available()
+            connection = source.cursor()
+            self._cursors.add(connection)
+        return AnalysisCursor(self, connection)
+
+    def cursor(self):
+        return self._new_cursor(self._connection)
+
+    def __getattr__(self, name):
+        return getattr(self._connection, name)
+
+    def execute(self, *args, **kwargs):
+        self._ensure_available()
+        result = self._connection.execute(*args, **kwargs)
+        return self if result is self._connection else result
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    def close(self):
+        with self._cursor_lock:
+            if self._closed:
+                return
+            self._closed = True
+            working = self._working
+            cursors = list(self._cursors)
+            self._cursors.clear()
+        self._stop.set()
+        self._monitor.join(timeout=3)
+        self._working = None
+        try:
+            for connection in [self._connection, *cursors]:
+                try:
+                    connection.interrupt()
+                except DuckDBError:
+                    pass
+            try:
+                for cursor in cursors:
+                    try:
+                        cursor.close()
+                    except DuckDBError:
+                        pass
+            finally:
+                self._connection.close()
+        finally:
+            try:
+                self._lease.close()
+            finally:
+                working.cleanup()
+
+
+class AnalysisCursor:
+    def __init__(self, owner, connection):
+        self._owner, self._connection = owner, connection
+
+    def __getattr__(self, name):
+        return getattr(self._connection, name)
+
+    def execute(self, *args, **kwargs):
+        self._owner._ensure_available()
+        result = self._connection.execute(*args, **kwargs)
+        return self if result is self._connection else result
+
+    def fetchmany(self, *args, **kwargs):
+        self._owner._ensure_available()
+        return self._connection.fetchmany(*args, **kwargs)
+
+    def fetch_record_batch(self, *args, **kwargs):
+        self._owner._ensure_available()
+        return self._connection.fetch_record_batch(*args, **kwargs)
+
+    def to_arrow_reader(self, *args, **kwargs):
+        self._owner._ensure_available()
+        return self._connection.to_arrow_reader(*args, **kwargs)
+
+    def cursor(self):
+        return self._owner._new_cursor(self._connection)
+
+    def close(self):
+        with self._owner._cursor_lock:
+            self._owner._cursors.discard(self._connection)
+        self._connection.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+def connect(settings):
+    import duckdb
+
+    root=Path(gettempdir()) / ('commitops-local-analysis-' + str(os.getuid() if hasattr(os,'getuid') else 'local'))
+    with _root_lock(root):
+        _reap_locked(root)
+        if shutil.disk_usage(root).free <= settings.disk_reserve:
+            raise AnalysisStorageError('Insufficient private analysis working storage')
+        working = TemporaryDirectory(prefix='job-', dir=root)
+        lease=(Path(working.name)/'.lease').open('w+b')
+        lease.write(b'0');lease.flush()
+        _lock(lease)
+    try:
+        connection = duckdb.connect(":memory:", config={
+            "autoinstall_known_extensions": False,
+            "autoload_known_extensions": False,
+            "threads": settings.duckdb_threads,
+            "memory_limit": settings.duckdb_memory_limit,
+            "max_temp_directory_size": settings.duckdb_spill_limit,
+            "temp_directory": working.name,
+        })
+    except BaseException:
+        lease.close()
+        working.cleanup()
+        raise
+    wrapper = AnalysisConnection(connection, working, lease, disk_reserve=settings.disk_reserve, memory_reserve=settings.memory_reserve)
+    wrapper.hardware = dict(settings.hardware)
+    return wrapper

package/engine/app/core/config.py

@@ -0,0 +1,10 @@
+from types import SimpleNamespace
+def get_settings():
+    from tempfile import gettempdir
+    from local_hardware import budget
+    limits = budget(gettempdir())
+    return SimpleNamespace(duckdb_threads=limits['cpu_threads'],
+                           duckdb_memory_limit=str(limits['duckdb_memory_bytes'])+'B',
+                           duckdb_spill_limit=str(limits['spill_bytes'])+'B',
+                           disk_reserve=limits['disk_reserve_bytes'],
+                           memory_reserve=limits['memory_reserve_bytes'], hardware=limits)