@hasna/economy 0.5.6 → 0.5.8

package/dist/mcp/index.js

@@ -5,6 +5,7 @@ import {
   MAX_INGEST_BYTES,
   MAX_INGEST_ROWS,
   assessCostFromDb,
+  buildCostSummary,
   cacheDir,
   calendarPeriodBounds,
   calendarPeriodWhere,
@@ -75,7 +76,7 @@ import {
   upsertUsageSnapshot,
   usageSnapshotFilterForPeriod,
   validateIngest
-} from "../chunks/index-vajzfzgv.js";
+} from "../chunks/index-ep1pkyr3.js";
 import {
   __require
 } from "../chunks/index-p35cyhc4.js";
@@ -85,7 +86,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // package.json
 var package_default = {
   name: "@hasna/economy",
-  version: "0.5.6",
+  version: "0.5.8",
   description: "AI coding cost tracker \u2014 CLI + MCP server + REST API for Claude Code, Codex, OpenCode, Cursor, Pi, and Hermes, with legacy Gemini CLI session and Gemini API billing ingestion",
   repository: {
     type: "git",
@@ -3705,7 +3706,7 @@ function backfillMachineId(db) {
   return { requests: Number(reqCount.changes), sessions: Number(sessCount.changes) };
 }
 async function recalculateZeroCostRequests(db) {
-  const { assessCostFromDb: assessCostFromDb2 } = await import("../chunks/pricing-vxejj1qa.js");
+  const { assessCostFromDb: assessCostFromDb2 } = await import("../chunks/pricing-nt31hf53.js");
   const zeroRows = db.prepare(`SELECT id, model, input_tokens, output_tokens, cache_read_tokens, cache_create_tokens, cache_create_5m_tokens, cache_create_1h_tokens
      FROM requests
      WHERE cost_usd = 0
@@ -3914,7 +3915,7 @@ async function postIngest(cloud, body) {
 }
 async function syncAllToCloud(cloud, opts = {}) {
   await runIngestJournalOperation(cloud, { action: "reconcile" });
-  const { openDatabase } = await import("../chunks/sqlite-store-gamn65xp.js");
+  const { openDatabase } = await import("../chunks/sqlite-store-jfy0e8b6.js");
   const scratch = openDatabase(":memory:", true);
   ensurePricingSeeded(scratch);
   const cachePath = opts.cachePath ?? getIngestCachePath();
@@ -3948,6 +3949,54 @@ function syncOutcomeLines(result) {
   return (result.collections ?? []).map((row) => `${row.source}: ${row.status}${row.error_code ? ` (${row.error_code})` : ""}`);
 }
 
+// src/lib/comparison-contract.ts
+function comparisonDateBounds(from, to) {
+  const valid = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value + "T00:00:00Z")) && new Date(value + "T00:00:00Z").toISOString().slice(0, 10) === value;
+  if (!valid(from) || !valid(to) || from > to) {
+    throw new RangeError("from and to must be real YYYY-MM-DD UTC dates with from <= to");
+  }
+  const end = new Date(to + "T00:00:00Z");
+  end.setUTCDate(end.getUTCDate() + 1);
+  const exclusive = end.toISOString().slice(0, 10);
+  if (!valid(exclusive))
+    throw new RangeError("to exceeds the supported UTC date range");
+  return { time_zone: "UTC", start_date: from, end_date_exclusive: exclusive };
+}
+function requireCurrentRangeStats(value, from, to) {
+  if (!value || typeof value !== "object")
+    throw new Error("COMPARISON_REPORT_UNAVAILABLE: Invalid response");
+  const report = value;
+  let money;
+  try {
+    money = requireCurrentCostSummary(report.money);
+  } catch {
+    throw new Error("COMPARISON_REPORT_UNAVAILABLE: The service must support comparison coverage");
+  }
+  for (const key of ["sessions", "requests", "tokens"]) {
+    if (!Number.isSafeInteger(report[key]) || report[key] < 0)
+      throw new Error("COMPARISON_REPORT_UNAVAILABLE: Invalid " + key);
+  }
+  if (report.cost !== money.total_usd || report.requests !== money.request_rows || report.tokens !== money.tokens || money.session_only_sessions !== 0 || money.session_only_value_usd !== 0 || money.requests !== money.request_rows) {
+    throw new Error("COMPARISON_REPORT_UNAVAILABLE: Inconsistent monetary coverage");
+  }
+  const knownRows = money.request_rows - money.unknown_price_requests;
+  const completeness = money.request_rows === 0 ? "no_records" : money.unknown_price_requests === 0 ? "complete" : knownRows > 0 ? "partial" : "unavailable";
+  if (money.completeness !== completeness || knownRows === 0 && money.total_usd !== 0 || money.sessions > money.request_rows || money.request_rows === 0 && money.tokens !== 0) {
+    throw new Error("COMPARISON_REPORT_UNAVAILABLE: Inconsistent request coverage");
+  }
+  const bounds = money.period_bounds;
+  if (!bounds.start_date || !bounds.end_date_exclusive || bounds.start_date >= bounds.end_date_exclusive) {
+    throw new Error("COMPARISON_REPORT_UNAVAILABLE: Missing comparison dates");
+  }
+  if (from !== undefined || to !== undefined) {
+    const expected = comparisonDateBounds(from, to);
+    if (bounds.start_date !== expected.start_date || bounds.end_date_exclusive !== expected.end_date_exclusive) {
+      throw new Error("COMPARISON_REPORT_UNAVAILABLE: Response dates do not match the requested range");
+    }
+  }
+  return report;
+}
+
 // src/lib/store/index.ts
 import { randomUUID } from "crypto";
 
@@ -4888,11 +4937,20 @@ function queryExportRows(db, type, period) {
   return db.prepare(`SELECT * FROM economy_effective_sessions WHERE ${where} ORDER BY started_at DESC`).all();
 }
 function queryRangeStats(db, from, to) {
-  const r = db.prepare(`SELECT COALESCE(SUM(cost_usd),0) as cost, COUNT(*) as requests,
-            COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens+cache_create_tokens),0) as tokens
-     FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?`).get(from, to);
+  const bounds = comparisonDateBounds(from, to);
+  const groups = db.prepare(`
+    SELECT cost_basis, model, CASE WHEN cost_usd = 0 THEN 1 WHEN cost_usd < 0 THEN 2 ELSE 0 END AS zero_cost,
+      SUM(cost_usd) AS cost_usd, COUNT(*) AS requests,
+      COALESCE(SUM(input_tokens),0) AS input_tokens, COALESCE(SUM(output_tokens),0) AS output_tokens,
+      COALESCE(SUM(cache_read_tokens),0) AS cache_read_tokens, COALESCE(SUM(cache_create_tokens),0) AS cache_create_tokens,
+      COALESCE(SUM(cache_create_1h_tokens),0) AS cache_create_1h_tokens
+    FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?
+    GROUP BY cost_basis, model, CASE WHEN cost_usd = 0 THEN 1 WHEN cost_usd < 0 THEN 2 ELSE 0 END
+  `).all(from, to);
+  const requestSessions = db.prepare("SELECT COUNT(DISTINCT session_id) AS sessions FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?").get(from, to);
+  const money = buildCostSummary("all", bounds, groups, { sessions: 0, requests: 0, tokens: 0, cost_usd: 0 }, requestSessions.sessions, listModelPricing(db));
   const s = db.prepare(`SELECT COUNT(*) as sessions FROM economy_effective_sessions WHERE DATE(started_at) BETWEEN ? AND ?`).get(from, to);
-  return { cost: r.cost, requests: r.requests, tokens: r.tokens, sessions: s.sessions };
+  return { cost: money.total_usd, money, requests: money.request_rows, tokens: money.tokens, sessions: s.sessions };
 }
 function queryForecast(db, now2 = new Date) {
   const month = resolveReportingInterval({ kind: "calendar", period: "month" }, now2);
@@ -4956,7 +5014,7 @@ class LocalStore2 {
   _db;
   async db() {
     if (!this._db) {
-      const { openDatabase } = await import("../chunks/sqlite-store-gamn65xp.js");
+      const { openDatabase } = await import("../chunks/sqlite-store-jfy0e8b6.js");
       this._db = openDatabase();
       ensurePricingSeeded(this._db);
     }
@@ -5233,7 +5291,7 @@ class ApiStore2 {
     return cloudListItems(this.cloud, "export", q({ type, period }));
   }
   async rangeStats(from, to) {
-    return cloudObject(this.cloud, "/compare", q({ from, to }));
+    return requireCurrentRangeStats(await cloudObject(this.cloud, "/compare", q({ from, to })), from, to);
   }
   async forecast() {
     return cloudObject(this.cloud, "/forecast");
@@ -5319,7 +5377,7 @@ function buildServer() {
   let _db;
   const localDb = async () => {
     if (!_db) {
-      const { openDatabase } = await import("../chunks/sqlite-store-gamn65xp.js");
+      const { openDatabase } = await import("../chunks/sqlite-store-jfy0e8b6.js");
       _db = openDatabase();
       ensurePricingSeeded(_db);
     }

package/dist/otel/index.js

@@ -3480,7 +3480,7 @@ async function pushIngestRows(cloud, scratch) {
 // package.json
 var package_default = {
   name: "@hasna/economy",
-  version: "0.5.6",
+  version: "0.5.8",
   description: "AI coding cost tracker \u2014 CLI + MCP server + REST API for Claude Code, Codex, OpenCode, Cursor, Pi, and Hermes, with legacy Gemini CLI session and Gemini API billing ingestion",
   repository: {
     type: "git",

package/dist/server/index.js

@@ -5578,7 +5578,7 @@ function isAuthorizedRequest(req, path) {
 // package.json
 var package_default = {
   name: "@hasna/economy",
-  version: "0.5.6",
+  version: "0.5.8",
   description: "AI coding cost tracker \u2014 CLI + MCP server + REST API for Claude Code, Codex, OpenCode, Cursor, Pi, and Hermes, with legacy Gemini CLI session and Gemini API billing ingestion",
   repository: {
     type: "git",
@@ -11839,6 +11839,25 @@ function buildBrief(db, opts = {}) {
   };
 }
 
+// src/lib/analytics.ts
+init_database();
+init_summary_contract();
+
+// src/lib/comparison-contract.ts
+init_summary_contract();
+function comparisonDateBounds(from, to) {
+  const valid = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value + "T00:00:00Z")) && new Date(value + "T00:00:00Z").toISOString().slice(0, 10) === value;
+  if (!valid(from) || !valid(to) || from > to) {
+    throw new RangeError("from and to must be real YYYY-MM-DD UTC dates with from <= to");
+  }
+  const end = new Date(to + "T00:00:00Z");
+  end.setUTCDate(end.getUTCDate() + 1);
+  const exclusive = end.toISOString().slice(0, 10);
+  if (!valid(exclusive))
+    throw new RangeError("to exceeds the supported UTC date range");
+  return { time_zone: "UTC", start_date: from, end_date_exclusive: exclusive };
+}
+
 // src/lib/analytics.ts
 function queryProjectDetail(db, nameOrPath, now = new Date) {
   const dailyBounds = resolveReportingInterval({ kind: "rolling", unit: "day", count: 14 }, now);
@@ -11888,11 +11907,20 @@ function queryExportRows(db, type, period) {
   return db.prepare(`SELECT * FROM economy_effective_sessions WHERE ${where} ORDER BY started_at DESC`).all();
 }
 function queryRangeStats(db, from, to) {
-  const r = db.prepare(`SELECT COALESCE(SUM(cost_usd),0) as cost, COUNT(*) as requests,
-            COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens+cache_create_tokens),0) as tokens
-     FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?`).get(from, to);
+  const bounds = comparisonDateBounds(from, to);
+  const groups = db.prepare(`
+    SELECT cost_basis, model, CASE WHEN cost_usd = 0 THEN 1 WHEN cost_usd < 0 THEN 2 ELSE 0 END AS zero_cost,
+      SUM(cost_usd) AS cost_usd, COUNT(*) AS requests,
+      COALESCE(SUM(input_tokens),0) AS input_tokens, COALESCE(SUM(output_tokens),0) AS output_tokens,
+      COALESCE(SUM(cache_read_tokens),0) AS cache_read_tokens, COALESCE(SUM(cache_create_tokens),0) AS cache_create_tokens,
+      COALESCE(SUM(cache_create_1h_tokens),0) AS cache_create_1h_tokens
+    FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?
+    GROUP BY cost_basis, model, CASE WHEN cost_usd = 0 THEN 1 WHEN cost_usd < 0 THEN 2 ELSE 0 END
+  `).all(from, to);
+  const requestSessions = db.prepare("SELECT COUNT(DISTINCT session_id) AS sessions FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?").get(from, to);
+  const money = buildCostSummary("all", bounds, groups, { sessions: 0, requests: 0, tokens: 0, cost_usd: 0 }, requestSessions.sessions, listModelPricing(db));
   const s = db.prepare(`SELECT COUNT(*) as sessions FROM economy_effective_sessions WHERE DATE(started_at) BETWEEN ? AND ?`).get(from, to);
-  return { cost: r.cost, requests: r.requests, tokens: r.tokens, sessions: s.sessions };
+  return { cost: money.total_usd, money, requests: money.request_rows, tokens: money.tokens, sessions: s.sessions };
 }
 function queryForecast(db, now = new Date) {
   const month = resolveReportingInterval({ kind: "calendar", period: "month" }, now);
@@ -12394,7 +12422,13 @@ function createDataHandler(db, actorId) {
       const to = url.searchParams.get("to")?.trim();
       if (!from || !to)
         return err("from and to are required (YYYY-MM-DD)");
-      return ok(queryRangeStats(db, from, to));
+      try {
+        return ok(queryRangeStats(db, from, to));
+      } catch (error) {
+        if (error instanceof RangeError)
+          return err(error.message);
+        throw error;
+      }
     }
     if (path === "/api/forecast" && method === "GET") {
       return ok(queryForecast(db));

package/dist/server/service-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-operations.d.ts","sourceRoot":"","sources":["../../src/server/service-operations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAuCxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAgkB5E,gHAAgH;AAChH,wBAAsB,uBAAuB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAe/G"}
+{"version":3,"file":"service-operations.d.ts","sourceRoot":"","sources":["../../src/server/service-operations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAuCxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAokB5E,gHAAgH;AAChH,wBAAsB,uBAAuB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAe/G"}

package/dist/server/service-worker.js

@@ -7264,6 +7264,25 @@ function buildBrief(db, opts = {}) {
   };
 }
 
+// src/lib/analytics.ts
+init_database();
+init_summary_contract();
+
+// src/lib/comparison-contract.ts
+init_summary_contract();
+function comparisonDateBounds(from, to) {
+  const valid = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value + "T00:00:00Z")) && new Date(value + "T00:00:00Z").toISOString().slice(0, 10) === value;
+  if (!valid(from) || !valid(to) || from > to) {
+    throw new RangeError("from and to must be real YYYY-MM-DD UTC dates with from <= to");
+  }
+  const end = new Date(to + "T00:00:00Z");
+  end.setUTCDate(end.getUTCDate() + 1);
+  const exclusive = end.toISOString().slice(0, 10);
+  if (!valid(exclusive))
+    throw new RangeError("to exceeds the supported UTC date range");
+  return { time_zone: "UTC", start_date: from, end_date_exclusive: exclusive };
+}
+
 // src/lib/analytics.ts
 function queryProjectDetail(db, nameOrPath, now = new Date) {
   const dailyBounds = resolveReportingInterval({ kind: "rolling", unit: "day", count: 14 }, now);
@@ -7313,11 +7332,20 @@ function queryExportRows(db, type, period) {
   return db.prepare(`SELECT * FROM economy_effective_sessions WHERE ${where} ORDER BY started_at DESC`).all();
 }
 function queryRangeStats(db, from, to) {
-  const r = db.prepare(`SELECT COALESCE(SUM(cost_usd),0) as cost, COUNT(*) as requests,
-            COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens+cache_create_tokens),0) as tokens
-     FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?`).get(from, to);
+  const bounds = comparisonDateBounds(from, to);
+  const groups = db.prepare(`
+    SELECT cost_basis, model, CASE WHEN cost_usd = 0 THEN 1 WHEN cost_usd < 0 THEN 2 ELSE 0 END AS zero_cost,
+      SUM(cost_usd) AS cost_usd, COUNT(*) AS requests,
+      COALESCE(SUM(input_tokens),0) AS input_tokens, COALESCE(SUM(output_tokens),0) AS output_tokens,
+      COALESCE(SUM(cache_read_tokens),0) AS cache_read_tokens, COALESCE(SUM(cache_create_tokens),0) AS cache_create_tokens,
+      COALESCE(SUM(cache_create_1h_tokens),0) AS cache_create_1h_tokens
+    FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?
+    GROUP BY cost_basis, model, CASE WHEN cost_usd = 0 THEN 1 WHEN cost_usd < 0 THEN 2 ELSE 0 END
+  `).all(from, to);
+  const requestSessions = db.prepare("SELECT COUNT(DISTINCT session_id) AS sessions FROM economy_effective_requests WHERE DATE(timestamp) BETWEEN ? AND ?").get(from, to);
+  const money = buildCostSummary("all", bounds, groups, { sessions: 0, requests: 0, tokens: 0, cost_usd: 0 }, requestSessions.sessions, listModelPricing(db));
   const s = db.prepare(`SELECT COUNT(*) as sessions FROM economy_effective_sessions WHERE DATE(started_at) BETWEEN ? AND ?`).get(from, to);
-  return { cost: r.cost, requests: r.requests, tokens: r.tokens, sessions: s.sessions };
+  return { cost: money.total_usd, money, requests: money.request_rows, tokens: money.tokens, sessions: s.sessions };
 }
 function queryForecast(db, now = new Date) {
   const month = resolveReportingInterval({ kind: "calendar", period: "month" }, now);
@@ -7426,7 +7454,7 @@ import { randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/economy",
-  version: "0.5.6",
+  version: "0.5.8",
   description: "AI coding cost tracker \u2014 CLI + MCP server + REST API for Claude Code, Codex, OpenCode, Cursor, Pi, and Hermes, with legacy Gemini CLI session and Gemini API billing ingestion",
   repository: {
     type: "git",
@@ -7945,7 +7973,13 @@ function createDataHandler(db, actorId) {
       const to = url.searchParams.get("to")?.trim();
       if (!from || !to)
         return err("from and to are required (YYYY-MM-DD)");
-      return ok(queryRangeStats(db, from, to));
+      try {
+        return ok(queryRangeStats(db, from, to));
+      } catch (error) {
+        if (error instanceof RangeError)
+          return err(error.message);
+        throw error;
+      }
     }
     if (path === "/api/forecast" && method === "GET") {
       return ok(queryForecast(db));

package/docs/comparison-coverage.md

@@ -0,0 +1,30 @@
+# Historical comparison coverage
+
+The comparison endpoint returns request/token counts and session counts as before.
+Its numeric `cost` field is a **known usage value subtotal**, following the same
+contract as the summary report's `total_usd`. It is not a billed or paid amount.
+
+`money` carries the full monetary evidence:
+
+- `complete_total_usd` is null for incomplete or empty selected request data.
+- Recorded metered amounts, estimated usage value and subscription-included
+  value are separate subtotals.
+- Unknown billing basis and unavailable pricing remain explicit counts.
+- `source_coverage: "not_established"` makes clear that completeness of the
+  selected stored records does not establish complete provider collection.
+- UTC bounds identify the selected inclusive date range through an exclusive
+  ending date.
+
+The CLI displays usage value as unavailable when the complete total is null,
+alongside the known subtotal and coverage. It calculates a monetary percentage
+only when both selected sets are complete and the baseline is nonzero.
+Genuinely recorded free usage can be complete zero; no records cannot.
+
+The hosted SDK refuses older responses without coverage and responses for a
+different date range. Deploy the service support before relying on a new
+comparison client. No stored original amount or billing classification is
+rewritten by this read-only reporting correction.
+
+Comparison usage values cover request rows. Lifetime-only session amounts are
+not allocated to dates by this endpoint. Session counts retain the existing
+started-within-range definition.

package/native/README.md

@@ -30,8 +30,28 @@ Never run real codes in a captured agent terminal. The helper obtains a
 single-use code, hands only that temporary code to the CoreImage renderer and
 clears the display within five minutes. `--self-test` decodes a synthetic QR;
 `test_pair_qr.py` proves transcript/agent-key refusal and credential confinement.
-The existing Identities human login flow remains the bootstrap when no human
-session exists; pairing does not create or assume an account.
+Without a saved human session, use
+`python3 native/Tools/pair-qr.py --tenant <workspace-id> --login-email <human-email>`.
+The helper opens the owner's Terminal, asks for confirmation before requesting
+one sign-in email, and reads the verification code there with echo disabled.
+It verifies a human principal and the selected workspace before displaying the
+one-use QR. The new setup session stays in memory. On renderer exit or catchable
+Terminal shutdown (HUP, TERM or Ctrl-C), setup makes one timeout-limited logout
+attempt and reports an unconfirmed result as a failure. Force-kill, a reboot,
+network failure or an interrupted verification response can prevent confirmation;
+check the account's sessions before retrying in those cases. An existing session
+supplied with `--session-ref` is retained.
+Only the temporary QR code reaches the renderer, and no response or verification
+code is returned to the agent terminal.
+
+For a first account, `--create-account` offers signup through the existing
+Identities flow instead of login. It requires direct confirmation in the owner
+Terminal before account creation or email delivery. It does not create an
+organization, grant an owner role, alter memberships or configure Economy's
+store binding. An existing-account refusal is not retried as login, and failed
+delivery/verification is not retried automatically. Never type the owner's code
+for them or copy it into an agent session. A source/fixture test does not prove
+real email delivery, account authority or a successful phone connection.
 
 The adapter verifies Economy's `/auth/session` subject, tenant, effective scopes
 and integer expiry. Viewer sign-in never requests write access. Refresh and period
@@ -129,3 +149,51 @@ fixture checks. Owner-facing screen captures go through Designs.
 Apple references: [MenuBarExtra](https://developer.apple.com/documentation/swiftui/menubarextra),
 [native design adoption](https://developer.apple.com/videos/play/wwdc2025/323/),
 [application delegate adaptor](https://developer.apple.com/documentation/swiftui/nsapplicationdelegateadaptor).
+
+## Vault-backed Mac release signing
+
+When the exact approved Developer ID certificate is not in the login Keychain,
+`Tools/prepare-signing.py` prepares a fresh private release Keychain. It does not
+unlock the login Keychain, sign the application, submit it to Apple or install it.
+Use the supported Secrets consumer to project these inputs directly to this
+process: `ECONOMY_SIGNING_CERTIFICATE_B64` (DER certificate),
+`ECONOMY_SIGNING_PRIVATE_KEY` (PEM), `ECONOMY_NOTARY_PRIVATE_KEY` (PEM),
+`ECONOMY_NOTARY_KEY_ID` and `ECONOMY_NOTARY_ISSUER`. Resolve the approved
+references and existing Apple team before execution. Never put their values in
+arguments, output or repository files.
+
+Run `python3 Tools/prepare-signing.py --output FRESH_SCRATCH_PATH --certificate EXACT_SHA1`.
+The output must be a new directory under the session Scratchpad. The helper
+imports credentials in memory, verifies the exact certificate, preserves the
+existing ordered search-list entries and default Keychain, and binds access to codesign. Its
+random password enters Apple's non-echoing prompt through its own terminal,
+never the command arguments. Apple's notarytool requires a regular key file and
+refuses stdin and FIFOs. The consumer writes that one input exclusively at mode
+0600 inside its fresh mode 0700 directory and passes only its path. It stores the
+profile in the encrypted Keychain; credential-consumer output is suppressed.
+The receipt explicitly names the sensitive input awaiting recoverable cleanup.
+If macOS registers the new Keychain, that owned addition is retained and reported
+in the receipt. The helper never replaces the shared search list; concurrent
+additions are retained. An explicit Keychain path also works without registration.
+
+Pass the resulting absolute Keychain path with `--keychain` to the existing
+`release.py sign-mac`, `submit-mac` and `check-mac` stages. Their separate
+signature, exact artifact, submission and acceptance checks still apply.
+Omitting the option retains the existing login-Keychain route. Preparation is
+not signing or notarization proof.
+
+Keep the preparation receipt and any failed artifact. Do not replay an uncertain
+submission. On failure, timeout, Ctrl-C, HUP or TERM, preparation settles its own
+child, locks the owned Keychain and inspects the original entries and default.
+An incomplete lock or inspection is explicitly recovery-unverified. SIGKILL,
+power loss and a killed parent cannot guarantee cleanup; inspect the retained
+artifact before retrying. After confirmed profile storage, preserve/read back
+the private input and remove that exact owned file through Trash; report pending
+cleanup on failure and retain its restricted permissions. Never treat preparation
+as complete release acceptance while sensitive cleanup remains. After the release,
+lock the exact release Keychain,
+preserve and read back its encrypted bytes through Trash, then retire only its
+owned registration through the supported Keychain operation. Verify other
+entries and the default remain; never replace the complete list during cleanup.
+The Keychain has a 15-minute idle lock; an expired lock requires a fresh
+preparation, not a password copied into a command or a login-Keychain change.