fix(gst): consolidate scoped artifact refusal and recovery handling

docs/LIVE_EVIDENCE_PROTOCOL.md

@@ -80,7 +80,10 @@ For a one-month or full-year exploratory run, record:
   each use one JSON row;
 - scenario: `single-period` or `full-year`;
 - outcome counts: eligible targets, downloaded, not filed, manually observed,
-  blocked, failed, duplicates;
+  blocked, failed, duplicates; schema V2 additionally records auto-drafted GSTR-2B
+  not-generated targets. V2 passing totals reconcile downloaded, not filed,
+  not generated, and manually observed targets to eligible targets. V1 evidence
+  remains valid without a synthesized not-generated count;
 - human verification checks;
 - service-worker and browser-restart checks for full-year runs;
 - clear-local-data result;

scripts/create-live-run-evidence-template.mjs

@@ -82,6 +82,7 @@ try {
   for (const field of [
     "downloaded",
     "not-filed",
+    "not-generated",
     "manually-observed",
     "blocked",
     "failed",
@@ -131,7 +132,7 @@ try {
   const zipSha256 = options["zip-sha256"] ?? readChromeZipSha256(packageJson.version);
 
   const evidence = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     evidenceId:
       options["evidence-id"] ??
       `pack-live-run-${new Date(startedAt).toISOString().slice(0, 10)}-${String(
@@ -259,6 +260,7 @@ function defaultCounts(outcome, eligibleTargets) {
     return {
       downloaded: eligibleTargets,
       notFiled: 0,
+      notGenerated: 0,
       manuallyObserved: 0,
       blocked: 0,
       failed: 0,
@@ -268,6 +270,7 @@ function defaultCounts(outcome, eligibleTargets) {
   return {
     downloaded: 0,
     notFiled: 0,
+    notGenerated: 0,
     manuallyObserved: 0,
     blocked: outcome === "blocked" ? eligibleTargets : 0,
     failed: outcome === "failed" ? eligibleTargets : 0,
@@ -368,6 +371,7 @@ function createDownloadEvidenceRows({
 
 function toCamelCountKey(key) {
   if (key === "not-filed") return "notFiled";
+  if (key === "not-generated") return "notGenerated";
   if (key === "manually-observed") return "manuallyObserved";
   return key;
 }

scripts/lib/live-run-evidence-types.ts

@@ -35,7 +35,7 @@ export type LiveRunEvidenceLimitation =
   | "browser-state-not-captured";
 
 export interface LiveRunEvidence {
-  schemaVersion: 1;
+  schemaVersion: 1 | 2;
   evidenceId: string;
   sourceCommit: string;
   gitTag: string;
@@ -93,6 +93,8 @@ export interface LiveRunEvidenceCounts {
   blocked: number;
   failed: number;
   duplicates: number;
+  /** Required by schema V2; absent in preserved V1 evidence. */
+  notGenerated?: number;
 }
 
 export interface LiveRunEvidenceChecks {

scripts/lib/live-run-evidence.ts

@@ -85,7 +85,7 @@ const LIVE_RUN_EVIDENCE_KEYS = [
   "mediaArtifacts",
 ];
 const BROWSER_KEYS = ["name", "version"];
-const COUNT_KEYS = [
+const COUNT_KEYS_V1 = [
   "eligibleTargets",
   "downloaded",
   "notFiled",
@@ -94,6 +94,7 @@ const COUNT_KEYS = [
   "failed",
   "duplicates",
 ];
+const COUNT_KEYS_V2 = [...COUNT_KEYS_V1, "notGenerated"];
 const CHECK_KEYS = [
   "humanVerifiedAccount",
   "humanVerifiedPeriods",
@@ -192,7 +193,7 @@ export function validateLiveRunEvidence(input: unknown): LiveRunEvidenceValidati
   if (!isRecord(input)) return { ok: false, errors: ["evidence must be an object"] };
 
   requireOnlyKeys(input, LIVE_RUN_EVIDENCE_KEYS, "evidence", errors);
-  requireExact(input.schemaVersion, 1, "schemaVersion", errors);
+  requireSchemaVersion(input.schemaVersion, errors);
   requirePattern(input.sourceCommit, HEX_40, "sourceCommit", errors);
   requirePattern(input.gitTag, GIT_TAG, "gitTag", errors);
   requirePattern(input.zipSha256, HEX_64, "zipSha256", errors);
@@ -225,7 +226,7 @@ export function validateLiveRunEvidence(input: unknown): LiveRunEvidenceValidati
   if (input.outcome === "pass" && input.profile !== "clean-test-profile") {
     errors.push("pass evidence must use clean-test-profile");
   }
-  validateCounts(input.counts, input.outcome, errors);
+  validateCounts(input.counts, input.outcome, input.returnType, input.schemaVersion, errors);
   validateChecks(input.checks, input.scenario, input.outcome, errors);
   validateDownloadEvidence(input.downloadEvidence, input, errors);
   validateLimitations(input.limitations, input.outcome, errors);
@@ -569,18 +570,29 @@ function expectedConcreteArtifactTypes(evidence: Record<string, unknown>): strin
   );
 }
 
-function validateCounts(input: unknown, outcome: unknown, errors: string[]): void {
+function validateCounts(
+  input: unknown,
+  outcome: unknown,
+  returnType: unknown,
+  schemaVersion: unknown,
+  errors: string[],
+): void {
   if (!isRecord(input)) {
     errors.push("counts must be an object");
     return;
   }
-  requireOnlyKeys(input, COUNT_KEYS, "counts", errors);
-  for (const field of COUNT_KEYS) {
+  const countKeys = schemaVersion === 2 ? COUNT_KEYS_V2 : COUNT_KEYS_V1;
+  requireOnlyKeys(input, countKeys, "counts", errors);
+  for (const field of countKeys) {
     requireNonNegativeInteger(input[field], `counts.${field}`, errors);
   }
-  if (!hasOnlyNumberCounts(input)) return;
-  const reconciled = input.downloaded + input.notFiled + input.manuallyObserved;
+  if (!hasOnlyNumberCounts(input, schemaVersion)) return;
+  const notGenerated = schemaVersion === 2 ? input.notGenerated : 0;
+  const reconciled = input.downloaded + input.notFiled + notGenerated + input.manuallyObserved;
   const observed = reconciled + input.blocked + input.failed;
+  if (notGenerated > 0 && returnType !== "GSTR-2B") {
+    errors.push("counts.notGenerated can be nonzero only for GSTR-2B");
+  }
   if (outcome === "pass" && reconciled === 0) {
     errors.push("counts must include at least one reconciled target");
   } else if (observed === 0) {
@@ -736,13 +748,8 @@ function assertNoSensitiveMarkers(input: unknown, errors: string[]): void {
   }
 }
 
-function requireExact(
-  value: unknown,
-  expected: number | string | boolean,
-  field: string,
-  errors: string[],
-): void {
-  if (value !== expected) errors.push(`${field} must be ${String(expected)}`);
+function requireSchemaVersion(value: unknown, errors: string[]): void {
+  if (value !== 1 && value !== 2) errors.push("schemaVersion must be 1 or 2");
 }
 
 function requirePattern(
@@ -817,15 +824,17 @@ function stableJson(value: unknown): string {
 
 function hasOnlyNumberCounts(
   input: Record<string, unknown>,
-): input is Record<keyof LiveRunEvidenceCounts, number> {
+  schemaVersion: unknown,
+): input is Record<keyof LiveRunEvidenceCounts, number> & { notGenerated?: number } {
   return (
     typeof input.downloaded === "number" &&
     typeof input.eligibleTargets === "number" &&
     typeof input.notFiled === "number" &&
     typeof input.manuallyObserved === "number" &&
     typeof input.blocked === "number" &&
     typeof input.failed === "number" &&
-    typeof input.duplicates === "number"
+    typeof input.duplicates === "number" &&
+    (schemaVersion !== 2 || typeof input.notGenerated === "number")
   );
 }
 

src/background/artifact-acquisition-state.ts

@@ -45,6 +45,8 @@ const ARTIFACT_ACQUISITION_CHECKPOINT_BASE_KEYS = [
   "state",
 ] as const;
 
+let artifactAcquisitionCheckpointMutationCriticalSection = Promise.resolve();
+
 export type ArtifactAcquisitionTarget = Pick<
   FiledReturnsDownloadScope,
   "artifactType" | "financialYear" | "period" | "returnType"
@@ -182,52 +184,96 @@ export async function clearMalformedArtifactAcquisitionCheckpoint(
 export async function persistArtifactAcquisitionIntent(
   input: Omit<ArtifactAcquisitionCheckpoint, "armedAt" | "state" | "downloadId">,
 ): Promise<void> {
-  const key = artifactAcquisitionCheckpointKey(input);
-  await browser.storage.session.set({
-    [key]: {
-      ...input,
-      armedAt: new Date().toISOString(),
-      state: "intent",
-    } satisfies ArtifactAcquisitionCheckpoint,
+  await runArtifactAcquisitionCheckpointMutation(async () => {
+    const key = artifactAcquisitionCheckpointKey(input);
+    await browser.storage.session.set({
+      [key]: {
+        ...input,
+        armedAt: new Date().toISOString(),
+        state: "intent",
+      } satisfies ArtifactAcquisitionCheckpoint,
+    });
   });
 }
 
 export async function persistArtifactAcquisitionDownloadId(
   input: Omit<ArtifactAcquisitionCheckpoint, "armedAt">,
 ): Promise<void> {
-  const key = artifactAcquisitionCheckpointKey(input);
-  const stored = await browser.storage.session.get(key);
-  await browser.storage.session.set({
-    [key]: {
-      ...input,
-      armedAt: armedAtFromCheckpoint(stored[key]) ?? new Date().toISOString(),
-      state: "download-observing",
-    } satisfies ArtifactAcquisitionCheckpoint,
+  await runArtifactAcquisitionCheckpointMutation(async () => {
+    const key = artifactAcquisitionCheckpointKey(input);
+    const stored = await browser.storage.session.get(key);
+    await browser.storage.session.set({
+      [key]: {
+        ...input,
+        armedAt: armedAtFromCheckpoint(stored[key]) ?? new Date().toISOString(),
+        state: "download-observing",
+      } satisfies ArtifactAcquisitionCheckpoint,
+    });
   });
 }
 
 export async function persistArtifactAcquisitionUnconfirmedDownload(
   input: Omit<ArtifactAcquisitionCheckpoint, "armedAt">,
 ): Promise<void> {
-  const key = artifactAcquisitionCheckpointKey(input);
-  const stored = await browser.storage.session.get(key);
-  await browser.storage.session.set({
-    [key]: {
-      ...input,
-      armedAt: armedAtFromCheckpoint(stored[key]) ?? new Date().toISOString(),
-      state: "download-unconfirmed",
-    } satisfies ArtifactAcquisitionCheckpoint,
+  await runArtifactAcquisitionCheckpointMutation(async () => {
+    const key = artifactAcquisitionCheckpointKey(input);
+    const stored = await browser.storage.session.get(key);
+    await browser.storage.session.set({
+      [key]: {
+        ...input,
+        armedAt: armedAtFromCheckpoint(stored[key]) ?? new Date().toISOString(),
+        state: "download-unconfirmed",
+      } satisfies ArtifactAcquisitionCheckpoint,
+    });
   });
 }
 
 export async function clearArtifactAcquisitionCheckpoint(
   target: ArtifactAcquisitionTarget,
   requestId: string,
+): Promise<{ ok: true } | { ok: false; reason: ArtifactAcquisitionCheckpointClearFailureReason }> {
+  return runArtifactAcquisitionCheckpointMutation(async () => {
+    const key = artifactAcquisitionCheckpointKey(target);
+    let stored: Record<string, unknown>;
+    try {
+      stored = await browser.storage.session.get(key);
+    } catch {
+      return { ok: false, reason: "storage-read-failed" };
+    }
+    if ((stored[key] as { requestId?: unknown } | undefined)?.requestId !== requestId) {
+      return { ok: false, reason: "checkpoint-invalid" };
+    }
+    try {
+      await browser.storage.session.remove(key);
+    } catch {
+      return { ok: false, reason: "storage-remove-failed" };
+    }
+    return { ok: true };
+  });
+}
+
+/** Clears an ordinary acquisition checkpoint, preserving the prior rejecting contract. */
+export async function clearArtifactAcquisitionCheckpointOrThrow(
+  target: ArtifactAcquisitionTarget,
+  requestId: string,
 ): Promise<void> {
-  const key = artifactAcquisitionCheckpointKey(target);
-  const stored = await browser.storage.session.get(key);
-  if ((stored[key] as { requestId?: unknown } | undefined)?.requestId === requestId) {
-    await browser.storage.session.remove(key);
+  const result = await clearArtifactAcquisitionCheckpoint(target, requestId);
+  if (!result.ok && result.reason !== "checkpoint-invalid") {
+    throw new Error(`artifact acquisition checkpoint clear failed: ${result.reason}`);
+  }
+}
+
+async function runArtifactAcquisitionCheckpointMutation<T>(action: () => Promise<T>): Promise<T> {
+  const previous = artifactAcquisitionCheckpointMutationCriticalSection;
+  let release: () => void = () => undefined;
+  artifactAcquisitionCheckpointMutationCriticalSection = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  await previous;
+  try {
+    return await action();
+  } finally {
+    release();
   }
 }
 

src/background/background-failure-fingerprint.ts

@@ -0,0 +1,42 @@
+// Enough to name a thrown failure, and nothing that could carry portal text.
+//
+// An error's message is not safe to render: it can quote a page, a URL, or a field value. Its
+// class name and the innermost stack symbol can name where a failure happened without repeating
+// anything the portal said -- but only if each is established to be this bundle's, rather than
+// merely made to look harmless.
+//
+// Stripping punctuation was the earlier approach and it was worse than no filter: a frame pointing
+// at a portal URL came back with its slashes deleted, so the value *looked* like a symbol
+// precisely because the characters that would have exposed it were gone. A filter that launders
+// its input is not a guard.
+//
+// This keeps durable failure fingerprints useful without retaining untrusted error text.
+
+// A frame names a place in this bundle only when the file it points at is this bundle's. The
+// symbol is what is kept; the URL is what proves the symbol is ours, and it is never kept. An
+// anonymous frame has no symbol to take, and a frame from anywhere else does not match at all.
+const BUNDLE_FRAME = /^\s*at\s+(?:async\s+)?([A-Za-z_$][\w$.]{0,59})\s+\(chrome-extension:\/\//u;
+
+// Every error class in this bundle ends in `Error`, as do the platform's own; `DOMException` is
+// the one exception the platform makes. Letters and that suffix cannot spell a GSTIN, an ARN, or
+// a URL, and a name that fails the shape degrades to `Error` rather than being laundered into one.
+const BUNDLE_ERROR_NAME = /^[A-Za-z]{1,40}Error$/u;
+
+function safeErrorName(name: string): string {
+  if (name === "DOMException") return name;
+  return BUNDLE_ERROR_NAME.test(name) ? name : "Error";
+}
+
+export function backgroundFailureFingerprint(error: unknown): string {
+  if (!(error instanceof Error)) return "NonError";
+  const name = safeErrorName(error.name || "Error");
+  const symbol =
+    typeof error.stack === "string"
+      ? (error.stack
+          .split("\n")
+          .slice(1)
+          .map((line) => BUNDLE_FRAME.exec(line)?.[1])
+          .find(Boolean) ?? "")
+      : "";
+  return symbol ? `${name} at ${symbol}` : name;
+}