rea-agents 6.5.0 → 6.7.0

package/dist/apktool/ApktoolProvider.js

@@ -1,23 +1,31 @@
-import { createHash, randomUUID } from "node:crypto";
-import { createWriteStream } from "node:fs";
-import { access, chmod, mkdir, mkdtemp, opendir, open, rm, stat, } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { countDecodedFiles } from "./ApktoolDecodedInventory.js";
+import { ApktoolWorkspace } from "./ApktoolWorkspace.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactFileCleanupFailure, artifactFilePrimaryFailure, artifactFileCancellationCause, } from "../artifacts/ArtifactFileOperation.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { capturedApktoolFailureOutput } from "./ApktoolCommandOutput.js";
+import { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { Transform } from "node:stream";
-import { pipeline } from "node:stream/promises";
 import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";
-import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { androidLocaleQualifierSchema, } from "../domain/apktool/apktoolResourceAnalysis.js";
-import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { createAnalysisExecution, createAnalysisExecutionEvidence, } from "../application/AnalysisProvider.js";
+import { apktoolResultSchemas, } from "../domain/apktool/apktoolResourceAnalysis.js";
+import { projectApktoolStringTables } from "./ApktoolStringTables.js";
+import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { err, ok } from "../domain/result.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
-import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
 import { OwnedCommandFailure, runOwnedCommand, } from "../process/OwnedCommand.js";
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { WindowsBatchCommandError } from "../process/WindowsBatchCommand.js";
 import { APKTOOL_COMMAND_ENV, ApktoolConfigurationFailure, apktoolConfigurationAvailability, apktoolInvocation, inspectApktoolClient, resolveApktoolCommand, } from "./ApktoolConfiguration.js";
-import { parseApktoolYml, parseDecodedStrings, parseManifestPackage, } from "./ApktoolDecodeOutput.js";
+import { parseApktoolYml, parseManifestPackage, } from "./ApktoolDecodeOutput.js";
 /** Stable identity for the Apktool resource-decoding provider. */
 export const APKTOOL_PROVIDER_IDENTITY = {
     id: "apktool",
@@ -27,58 +35,15 @@ export const APKTOOL_PROVIDER_IDENTITY = {
 const DECODE_TIMEOUT_MS = 600_000;
 const DECODE_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 const MANIFEST_MAX_BYTES = 512 * 1024;
-const STRINGS_XML_MAX_BYTES = 8 * 1024 * 1024;
-const MAX_STRINGS = 2_000;
 const MAX_DECODED_ENTRIES_VISITED = 100_000;
 const STDERR_EXCERPT_BYTES = 512;
 const throwIfCancelled = (operation, signal) => {
     if (signal?.aborted === true)
-        throw new AnalysisCancelledError(operation);
+        throw new AnalysisCancelledError(operation, { cause: signal.reason });
 };
-/** Read at most the byte budget plus one byte, before decoding UTF-8. */
-const readBoundedText = async (path, budget, operation, signal) => {
-    const file = await open(path, "r").catch((cause) => {
-        if (cause.code === "ENOENT")
-            return null;
-        throw cause;
-    });
-    if (file === null)
-        return { text: null, truncated: false };
-    try {
-        throwIfCancelled(operation, signal);
-        const bytes = Buffer.alloc(budget + 1);
-        let length = 0;
-        while (length < bytes.length) {
-            throwIfCancelled(operation, signal);
-            const result = await file.read(bytes, length, bytes.length - length, null);
-            if (result.bytesRead === 0)
-                break;
-            length += result.bytesRead;
-        }
-        throwIfCancelled(operation, signal);
-        const truncated = length > budget;
-        // A prefix may end within a UTF-8 character; omit those trailing bytes.
-        try {
-            const decoder = new TextDecoder("utf-8", { fatal: true });
-            return {
-                text: decoder.decode(bytes.subarray(0, Math.min(length, budget)), {
-                    stream: truncated,
-                }),
-                truncated,
-            };
-        }
-        catch (cause) {
-            throw new AnalysisProtocolError(`apktool produced invalid UTF-8 in ${path}`, { cause });
-        }
-    }
-    finally {
-        await file.close();
-    }
-};
-const localeQualifier = (locale) => locale.replace(/^([a-z]{2,3})-([A-Z]{2}|[0-9]{3})$/u, "$1-r$2");
-const runApktool = async (operation, selection, arguments_, limits, signal, environment, onCleanupOwner) => {
+const runApktool = async (operation, targetPath, selection, arguments_, limits, signal, environment, commands, root) => {
     if (signal?.aborted === true)
-        return err(new AnalysisCancelledError(operation));
+        return err(new AnalysisCancelledError(operation, { cause: signal?.reason }));
     let invocation;
     try {
         invocation = apktoolInvocation(selection, arguments_, environment);
@@ -94,6 +59,9 @@ const runApktool = async (operation, selection, arguments_, limits, signal, envi
             command: invocation.command,
             arguments: invocation.arguments,
             windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+            // Apktool launchers are commonly interpreter scripts, so ownership is
+            // proved by the run token rather than the launcher's argv prefix.
+            expectedCommand: null,
             runId: randomUUID(),
             hostEnvironment: environment,
         }, {
@@ -103,87 +71,62 @@ const runApktool = async (operation, selection, arguments_, limits, signal, envi
         return ok({ stdout: output.stdout.text, stderr: output.stderr.text });
     }
     catch (cause) {
-        if (!(cause instanceof OwnedCommandFailure))
-            return err(new AnalysisProtocolError(`apktool failed for ${operation}`, { cause }));
-        if (cause.cleanupOwner !== undefined)
-            onCleanupOwner(cause.cleanupOwner);
-        const output = cause.snapshot;
-        const capturedOutput = output === null
-            ? undefined
-            : {
-                stdout: output.stdout.text,
-                stderr: output.stderr.text,
-                truncated: output.diagnosticTruncated === true,
-                stdout_bytes: output.stdout.bytes,
-                stderr_bytes: output.stderr.bytes,
-                exit_code: output.exitCode ?? null,
-                signal: output.signal ?? null,
-            };
-        const cleanup = cause.cleanupFailure === null
-            ? undefined
-            : {
-                reason: cause.cleanupFailure,
-                resources: cause.resources,
-            };
-        if (cause.reason === "cancelled")
-            return err(new AnalysisCancelledError(operation, {
-                cause,
-                ...(cleanup === undefined ? {} : { cleanup }),
-                ...(capturedOutput === undefined ? {} : { capturedOutput }),
-            }));
-        if (cause.reason === "timeout")
-            return err(new AnalysisTimeoutError(operation, limits.timeoutMs, {
-                cause,
-                ...(cleanup === undefined ? {} : { cleanup }),
-                ...(capturedOutput === undefined ? {} : { capturedOutput }),
-            }));
-        if (cause.reason === "output-limit")
-            return err(new AnalysisResourceConstraintError(operation, "memory", `apktool output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`, { max_output_bytes: limits.maxOutputBytes }, {
-                cause,
-                ...(cleanup === undefined ? {} : { cleanup }),
-                ...(capturedOutput === undefined ? {} : { capturedOutput }),
-            }));
-        return err(new AnalysisUnsupportedTargetError(operation, selection.command, output?.stderr.text.trim().slice(0, STDERR_EXCERPT_BYTES) ||
-            `apktool exited with code ${String(output?.exitCode ?? "unknown")} for ${operation}`, {
-            cause,
-            ...(cleanup === undefined ? {} : { cleanup }),
-            ...(capturedOutput === undefined ? {} : { capturedOutput }),
-        }));
+        return err(commands.retainFailure(cause, apktoolCommandFailure(cause, operation, targetPath, selection, limits), operation, root));
     }
 };
-/** Count files while bounding streamed directory-entry traversal. */
-const countDecodedFiles = async (root, signal, operation) => {
-    let count = 0;
-    let capped = false;
-    let visited = 0;
-    const directories = [root];
-    const locales = [];
-    while (directories.length > 0 && !capped) {
-        throwIfCancelled(operation, signal);
-        const directory = directories.pop();
-        for await (const entry of await opendir(directory)) {
-            throwIfCancelled(operation, signal);
-            if (visited >= MAX_DECODED_ENTRIES_VISITED) {
-                capped = true;
-                break;
-            }
-            visited += 1;
-            const path = join(directory, entry.name);
-            if (entry.isDirectory()) {
-                directories.push(path);
-                if (directory === join(root, "res")) {
-                    const match = /^values-(.+)$/u.exec(entry.name);
-                    if (match !== null &&
-                        androidLocaleQualifierSchema.safeParse(match[1]).success &&
-                        (await access(join(path, "strings.xml")).then(() => true, () => false)))
-                        locales.push(match[1]);
-                }
-            }
-            else if (entry.isFile())
-                count += 1;
-        }
-    }
-    return { count, capped, locales: locales.sort() };
+const apktoolCommandFailure = (cause, operation, targetPath, selection, limits) => {
+    const capturedOutput = capturedApktoolFailureOutput(cause);
+    if (!(cause instanceof OwnedCommandFailure))
+        return new ProviderAdapterError("apktool", operation, {
+            cause,
+            diagnostics: {
+                selected_command: selection.command,
+                target_path: targetPath,
+            },
+            ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        });
+    const output = cause.snapshot;
+    if (cause.reason === "cancelled")
+        return new AnalysisCancelledError(operation, {
+            cause: cause.cancellation?.reason,
+            ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        });
+    if (cause.reason === "timeout")
+        return new AnalysisTimeoutError(operation, limits.timeoutMs, {
+            cause,
+            ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        });
+    if (cause.reason === "output-limit")
+        return new AnalysisResourceConstraintError(operation, "memory", `apktool output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`, { max_output_bytes: limits.maxOutputBytes }, {
+            cause,
+            ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        });
+    // A physical launcher/capture failure does not establish target refusal.
+    // Only a fully collected ordinary nonzero decode exit carries that meaning.
+    if (cause.processError !== undefined ||
+        cause.collectionFailure ||
+        cause.preparationFailure !== undefined ||
+        output === null ||
+        output.exitCode === null ||
+        output.exitCode === undefined ||
+        output.exitCode === 0 ||
+        output.signal !== null ||
+        output.outputIncomplete === true ||
+        output.diagnosticTruncated === true)
+        return new ProviderAdapterError("apktool", operation, {
+            cause,
+            userMessage: `The selected Apktool command failed while decoding ${targetPath}`,
+            diagnostics: {
+                selected_command: selection.command,
+                target_path: targetPath,
+            },
+            ...(capturedOutput === undefined ? {} : { capturedOutput }),
+        });
+    return new AnalysisUnsupportedTargetError(operation, targetPath, output?.stderr.text.trim().slice(0, STDERR_EXCERPT_BYTES) ||
+        `apktool exited with code ${String(output?.exitCode ?? "unknown")} for ${operation}`, {
+        cause,
+        ...(capturedOutput === undefined ? {} : { capturedOutput }),
+    });
 };
 /**
  * Apktool resource decoding over a caller-selected launcher.
@@ -194,9 +137,9 @@ const countDecodedFiles = async (root, signal, operation) => {
  */
 export class ApktoolProvider {
     selectedEnvironment;
-    workspaces = new Set();
+    #artifacts = new ArtifactResourceScope();
     removeWorkspace;
-    #pendingCommandOwners = new Map();
+    #commands = new ApktoolCommandCleanup();
     #shutdown = new AbortController();
     #active = new Set();
     #closing = false;
@@ -206,9 +149,7 @@ export class ApktoolProvider {
             options.environment === undefined
                 ? undefined
                 : snapshotEnvironment(options.environment);
-        this.removeWorkspace =
-            options.removeWorkspace ??
-                ((path) => rm(path, { recursive: true, force: true }));
+        this.removeWorkspace = options.removeWorkspace;
     }
     operationEnvironment() {
         const ambient = snapshotEnvironment(process.env);
@@ -229,13 +170,20 @@ export class ApktoolProvider {
         const operationSignal = signal === undefined
             ? this.#shutdown.signal
             : AbortSignal.any([signal, this.#shutdown.signal]);
-        return this.#track(this.#inspectAvailability(operationSignal));
+        return this.#track(this.#commands
+            .run(() => this.#artifacts.run(() => this.#inspectAvailability(operationSignal)), "inspect_apktool_client")
+            .catch((cause) => {
+            throw analysisClientFailureForOperation(cause, "apktool", "inspect_apktool_client");
+        }));
     }
     async #inspectAvailability(signal) {
         const environment = this.operationEnvironment();
         try {
             const selection = await resolveApktoolCommand(environment, process.platform, signal);
-            await inspectApktoolClient(selection, signal, environment);
+            await inspectApktoolClient(selection, this.#commands, {
+                signal,
+                environment,
+            });
             throwIfCancelled("inspect_apktool_client", signal);
             return {
                 status: "available",
@@ -248,8 +196,9 @@ export class ApktoolProvider {
             };
         }
         catch (cause) {
-            if (cause instanceof ApktoolConfigurationFailure)
+            if (cause instanceof ApktoolConfigurationFailure) {
                 return apktoolConfigurationAvailability(cause);
+            }
             throw cause;
         }
     }
@@ -269,29 +218,33 @@ export class ApktoolProvider {
         const signal = options?.signal === undefined
             ? this.#shutdown.signal
             : AbortSignal.any([options.signal, this.#shutdown.signal]);
-        return this.#track(this.#execute(request, signal));
+        return this.#track(this.#commands
+            .run(() => this.#artifacts.run(() => this.#execute(request, signal)), request.operation)
+            .catch((cause) => err(analysisClientFailureForOperation(cause, "apktool", request.operation))));
     }
     async #execute(request, signal) {
         if (signal?.aborted === true)
-            return err(new AnalysisCancelledError(request.operation));
+            return err(new AnalysisCancelledError(request.operation, { cause: signal.reason }));
         const environment = this.operationEnvironment();
         let selection;
         let identity;
         try {
             selection = await resolveApktoolCommand(environment, process.platform, signal);
-            identity = await inspectApktoolClient(selection, signal, environment);
+            identity = await inspectApktoolClient(selection, this.#commands, {
+                signal,
+                environment,
+            });
         }
         catch (cause) {
-            if (cause instanceof AnalysisCancelledError ||
-                cause instanceof AnalysisTimeoutError)
-                return err(cause);
+            if (cause instanceof AnalysisError)
+                return err(analysisClientFailureForOperation(cause, "apktool", request.operation));
             if (cause instanceof ApktoolConfigurationFailure) {
                 return err(providerConfigurationRefusal(APKTOOL_PROVIDER_IDENTITY.id, request.operation, cause));
             }
             return err(new AnalysisProtocolError(`apktool version probe failed for ${request.operation}`, { cause }));
         }
         if (signal.aborted)
-            return err(new AnalysisCancelledError(request.operation));
+            return err(new AnalysisCancelledError(request.operation, { cause: signal.reason }));
         const client = {
             command: selection.command,
             command_source: selection.commandSource,
@@ -302,8 +255,10 @@ export class ApktoolProvider {
             version: identity.version,
         };
         if (request.operation === "inspect_apktool_client")
-            return ok(createAnalysisExecution({ client }, provider));
-        return this.decodeResources(request.operation, selection, environment, client, provider, request.input, signal);
+            return ok(createAnalysisExecution({ client }, provider, {
+                limitations: identity.limitations,
+            }));
+        return this.decodeResources(request.operation, selection, environment, client, provider, request.input, identity.limitations, signal);
     }
     #track(operation) {
         const settled = operation.then(() => undefined, () => undefined);
@@ -314,104 +269,45 @@ export class ApktoolProvider {
     async #drainAndClean() {
         await Promise.all(this.#active);
         const failures = [];
-        for (const [owner, root] of this.#pendingCommandOwners) {
-            try {
-                const stopped = await owner.stop();
-                if (stopped.status === "incomplete")
-                    throw new Error(stopped.reason);
-                this.#pendingCommandOwners.delete(owner);
-            }
-            catch (cause) {
-                failures.push(new Error(`apktool process cleanup remains incomplete for ${root}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
-            }
-        }
-        if (failures.length > 0)
-            throw new AggregateError(failures, "Apktool process cleanup failed");
-        for (const path of this.workspaces) {
+        for (const close of [
+            () => this.#commands.close(),
+            () => this.#artifacts.close(),
+        ]) {
             try {
-                await this.removeWorkspace(path);
-                this.workspaces.delete(path);
+                await close();
             }
             catch (cause) {
-                failures.push(cause);
+                failures.push(analysisClientFailureForOperation(cause, "apktool", "close"));
             }
         }
-        if (failures.length > 0)
-            throw new AggregateError(failures, "Apktool workspace cleanup failed");
+        const first = failures.shift();
+        if (first === undefined)
+            return;
+        throw failures.reduce((primary, cleanup) => analysisErrorWithCleanupFailure(primary, cleanup, "close").bindCleanupDependencies([primary, cleanup]), first);
     }
-    async decodeResources(operation, selection, environment, client, provider, input, signal) {
-        const root = await mkdtemp(join(tmpdir(), "rea-apktool-"));
-        this.workspaces.add(root);
+    async decodeResources(operation, selection, environment, client, provider, input, clientLimitations, signal) {
+        const runtime = await PrivateRuntimeRoot.create({ prefix: "rea-apktool-" });
+        const resources = new ApktoolWorkspace(runtime, this.#commands, this.removeWorkspace);
+        const root = resources.path;
         const workspace = join(root, "decoded");
         const snapshot = join(root, "input.apk");
         const framework = join(root, "framework");
-        let cleanupFailure = null;
-        // The workspace is removed before the result is returned, so an
-        // unremovable workspace is reported instead of silently abandoned.
-        const removeWorkspace = async () => {
-            if ([...this.#pendingCommandOwners.values()].includes(root)) {
-                cleanupFailure = `The decode workspace is retained until its apktool process stops: ${root}`;
-                return;
-            }
-            try {
-                await this.removeWorkspace(root);
-                this.workspaces.delete(root);
-            }
-            catch {
-                cleanupFailure = `The decode workspace could not be removed: ${root}`;
-            }
-        };
-        const failureWithCleanup = (failure) => cleanupFailure === null
-            ? failure
-            : analysisErrorWithCleanupFailure(failure, new ProviderCleanupError(APKTOOL_PROVIDER_IDENTITY.id, [root], { reason: cleanupFailure }, { operation }), operation);
-        let source;
-        let sourceAdmissionFailed = false;
+        const lease = new AnalysisCleanupLease(() => resources.close(), [root]);
+        const owner = { kind: "lease", resource: root, lease };
+        this.#artifacts.retain(owner);
+        let result;
+        let completedDecode;
+        let stoppedAt = "metadata";
+        const limitations = [
+            ...clientLimitations,
+            "Decoding skips smali (--no-src); Java-source recovery belongs to the JADX family",
+        ];
         try {
-            throwIfCancelled(operation, signal);
-            sourceAdmissionFailed = true;
-            source = await openRegularFile(input.path, {
-                symlinks: "follow",
-                ...(signal === undefined ? {} : { signal }),
-            });
-            const sourceInfo = await source.stat();
-            sourceAdmissionFailed = false;
-            const sourceSize = sourceInfo.size;
-            let copiedBytes = 0;
-            const sourceHash = createHash("sha256");
-            const boundedSource = new Transform({
-                transform(chunk, _encoding, callback) {
-                    copiedBytes += chunk.length;
-                    if (copiedBytes > sourceSize) {
-                        callback(new AnalysisInputError(operation, {
-                            cause: new Error(`The selected APK changed while being copied: ${input.path}`),
-                        }));
-                        return;
-                    }
-                    sourceHash.update(chunk);
-                    callback(null, chunk);
-                },
-            });
-            await pipeline(source.createReadStream({
-                start: 0,
-                end: sourceSize,
-                autoClose: false,
-                ...(signal === undefined ? {} : { signal }),
-            }), boundedSource, createWriteStream(snapshot, { flags: "wx", mode: 0o600 }), signal === undefined ? {} : { signal });
-            const finalSourceInfo = await source.stat();
-            if (copiedBytes !== sourceSize ||
-                !sameRegularFileState(sourceInfo, finalSourceInfo))
-                throw new AnalysisInputError(operation, {
-                    cause: new Error(`The selected APK changed while being copied: ${input.path}`),
-                });
-            const sha256 = sourceHash.digest("hex");
-            await source.close();
-            source = undefined;
-            await chmod(snapshot, 0o400);
-            throwIfCancelled(operation, signal);
-            const snapshotInfo = await stat(snapshot);
+            const identity = await resources.snapshotInput(input.path, operation, signal);
+            const sha256 = identity.sha256;
             await mkdir(workspace);
             await mkdir(framework);
-            const decoded = await runApktool(operation, selection, [
+            const decoded = await runApktool(operation, input.path, selection, [
                 "d",
                 "--no-src",
                 "-f",
@@ -423,121 +319,144 @@ export class ApktoolProvider {
             ], {
                 timeoutMs: DECODE_TIMEOUT_MS,
                 maxOutputBytes: DECODE_MAX_OUTPUT_BYTES,
-            }, signal, environment, (owner) => this.#pendingCommandOwners.set(owner, root));
+            }, signal, environment, this.#commands, root);
             if (!decoded.ok) {
-                await removeWorkspace();
-                return err(failureWithCleanup(decoded.error));
+                throw decoded.error;
             }
+            completedDecode = {
+                client,
+                target: { path: input.path, bytes: identity.bytes, sha256 },
+                locale: input.locale ?? null,
+                coverage: "partial",
+            };
             throwIfCancelled(operation, signal);
-            const yml = await readBoundedText(join(workspace, "apktool.yml"), MANIFEST_MAX_BYTES, operation, signal);
+            const yml = await resources.readText(join(workspace, "apktool.yml"), MANIFEST_MAX_BYTES, signal);
             if (yml.text === null || yml.truncated) {
                 throw new AnalysisProtocolError(`apktool produced missing or oversized apktool.yml: ${input.path}`);
             }
             const metadata = parseApktoolYml(yml.text);
-            const manifestRead = await readBoundedText(join(workspace, "AndroidManifest.xml"), MANIFEST_MAX_BYTES, operation, signal);
+            completedDecode.metadata = {
+                version_name: metadata.versionName,
+                version_code: metadata.versionCode,
+                min_sdk_version: metadata.minSdkVersion,
+                target_sdk_version: metadata.targetSdkVersion,
+            };
+            stoppedAt = "manifest";
+            const manifestRead = await resources.readText(join(workspace, "AndroidManifest.xml"), MANIFEST_MAX_BYTES, signal);
             const manifest = manifestRead.text;
+            completedDecode.manifest = manifest;
+            if (manifestRead.truncated) {
+                limitations.push(`manifest is truncated at ${String(MANIFEST_MAX_BYTES)} bytes`);
+            }
             const packageName = manifest === null || manifestRead.truncated
                 ? null
                 : parseManifestPackage(manifest);
-            const stringsDirectory = input.locale === undefined
-                ? "values"
-                : `values-${localeQualifier(input.locale)}`;
-            const stringsRead = input.include_strings
-                ? await readBoundedText(join(workspace, "res", stringsDirectory, "strings.xml"), STRINGS_XML_MAX_BYTES, operation, signal)
-                : { text: null, truncated: false };
-            // Do not parse an incomplete XML document as though its projection were complete.
-            const stringsXml = stringsRead.truncated ? null : stringsRead.text;
-            const parsedStrings = stringsXml === null
-                ? { entries: [], unparsedCount: 0 }
-                : parseDecodedStrings(stringsXml);
-            const bounded = parsedStrings.entries.slice(0, MAX_STRINGS);
-            const files = await countDecodedFiles(workspace, signal, operation);
+            completedDecode.metadata.package_name = packageName;
+            stoppedAt = "inventory";
+            const inventory = await countDecodedFiles(resources, workspace, signal, MAX_DECODED_ENTRIES_VISITED);
+            const files = inventory.ok ? inventory.value : inventory.error.partial;
+            completedDecode.locales = [...files.locales];
+            completedDecode.decoded_file_count = files.count;
+            if (files.unreadableStringsTables.length > 0) {
+                limitations.push(`String tables omitted because they are not regular files: ${files.unreadableStringsTables.map((table) => `${JSON.stringify(table.path)} (${table.kind})`).join(", ")}`);
+            }
+            if (files.otherStringsTables.length > 0) {
+                limitations.push(`Other strings tables are not selected by locale; their resource configuration suffixes are preserved without inferring Android runtime matching: ${files.otherStringsTables.map((table) => JSON.stringify(table)).join(", ")}`);
+            }
+            if (files.capped) {
+                limitations.push(`Decoded workspace enumeration stopped after ${String(MAX_DECODED_ENTRIES_VISITED)} entries; decoded_file_count and locales may be partial`);
+            }
+            if (!inventory.ok)
+                throw inventory.error.cause;
             throwIfCancelled(operation, signal);
-            const coverage = (stringsXml !== null && parsedStrings.entries.length > MAX_STRINGS) ||
+            stoppedAt = "string projection";
+            const projection = await projectApktoolStringTables(resources, workspace, input, signal);
+            const projectedStrings = projection.ok
+                ? projection.value
+                : projection.error.partial;
+            limitations.push(...projectedStrings.limitations);
+            const coverage = projectedStrings.coverage === "partial" ||
                 manifestRead.truncated ||
-                stringsRead.truncated ||
-                parsedStrings.unparsedCount > 0 ||
-                files.capped
+                files.capped ||
+                files.unreadableStringsTables.length > 0
                 ? "partial"
                 : "complete";
-            await removeWorkspace();
-            return ok(createAnalysisExecution({
-                client,
-                target: { path: input.path, bytes: snapshotInfo.size, sha256 },
-                metadata: {
-                    version_name: metadata.versionName,
-                    version_code: metadata.versionCode,
-                    min_sdk_version: metadata.minSdkVersion,
-                    target_sdk_version: metadata.targetSdkVersion,
-                    package_name: packageName,
-                },
-                manifest,
-                strings: bounded,
-                locale: input.locale ?? null,
-                locales: files.locales,
-                decoded_file_count: files.count,
-                coverage,
-            }, provider, {
-                limitations: [
-                    "Decoding skips smali (--no-src); Java-source recovery belongs to the JADX family",
-                    ...(input.locale !== undefined &&
-                        stringsRead.text === null &&
-                        input.include_strings
-                        ? [`No strings.xml was found for locale ${input.locale}`]
-                        : []),
-                    ...(input.include_strings &&
-                        stringsRead.text === null &&
-                        input.locale === undefined
-                        ? [
-                            "No default res/values/strings.xml was found in the decoded workspace",
-                        ]
-                        : []),
-                    ...(parsedStrings.unparsedCount > 0
-                        ? [
-                            `String entries omitted due to malformed XML or unsupported markup: ${String(parsedStrings.unparsedCount)}`,
-                        ]
-                        : []),
-                    ...(parsedStrings.entries.length > MAX_STRINGS
-                        ? [
-                            `strings reports the first ${String(MAX_STRINGS)} of ${String(parsedStrings.entries.length)} entries`,
-                        ]
-                        : []),
-                    ...(manifestRead.truncated
-                        ? [
-                            `manifest is truncated at ${String(MANIFEST_MAX_BYTES)} bytes`,
-                        ]
-                        : []),
-                    ...(stringsRead.truncated
-                        ? [
-                            `strings.xml exceeds the ${String(STRINGS_XML_MAX_BYTES)}-byte projection budget`,
-                        ]
-                        : []),
-                    ...(files.capped
-                        ? [
-                            `Decoded workspace enumeration stopped after ${String(MAX_DECODED_ENTRIES_VISITED)} entries; decoded_file_count and locales may be partial`,
-                        ]
-                        : []),
-                    ...(cleanupFailure === null ? [] : [cleanupFailure]),
-                ],
+            completedDecode.strings = [...projectedStrings.strings];
+            if (input.locales !== undefined)
+                completedDecode.string_tables = [...projectedStrings.tables];
+            completedDecode.coverage = coverage;
+            if (!projection.ok)
+                throw projection.error.cause;
+            result = ok(createAnalysisExecution(apktoolResultSchemas.decode_android_resources.parse(completedDecode), provider, {
+                subject: { path: input.path, sha256, format: "apk" },
+                limitations,
             }));
         }
         catch (cause) {
-            await removeWorkspace();
-            return err(failureWithCleanup(signal?.aborted === true
-                ? new AnalysisCancelledError(operation, { cause })
-                : sourceAdmissionFailed
-                    ? new AnalysisInputError(operation, { cause })
-                    : cause instanceof AnalysisInputError
-                        ? cause
-                        : cause instanceof AnalysisCancelledError ||
-                            cause instanceof AnalysisProtocolError
-                            ? cause
-                            : new AnalysisProtocolError("Apktool resource projection failed", {
-                                cause,
-                            })));
+            const physical = artifactFilePrimaryFailure(cause);
+            const primary = physical instanceof AnalysisError
+                ? physical
+                : physical instanceof ArtifactReaderFailure &&
+                    physical.reason === "cancelled"
+                    ? new AnalysisCancelledError(operation, {
+                        cause: artifactFileCancellationCause(physical),
+                    })
+                    : new AnalysisProtocolError("Apktool resource projection failed", {
+                        cause: physical,
+                    });
+            const failure = analysisClientFailureForOperation(cause, "apktool", operation);
+            if (cause instanceof ArtifactReaderFailure &&
+                cause.cleanup !== undefined &&
+                !(cause instanceof ArtifactFileCleanupFailure))
+                new AnalysisCleanupLeaseGroup(failure, [lease]);
+            const retained = physical === cause && cause instanceof AnalysisError
+                ? cause
+                : failure.cleanupIncomplete
+                    ? analysisErrorWithCleanupFailure(primary, failure, operation).bindCleanupDependencies([primary, failure])
+                    : primary;
+            if (completedDecode !== undefined &&
+                retained.partialObservation === undefined) {
+                limitations.push(`Decode observation stopped during ${stoppedAt}; fields not yet observed are omitted`);
+                const partialExecution = createAnalysisExecution({ ...completedDecode, coverage: "partial" }, provider, {
+                    subject: {
+                        path: input.path,
+                        sha256: completedDecode.target.sha256,
+                        format: "apk",
+                    },
+                    limitations,
+                });
+                retained.retainPartialObservation(createAnalysisExecutionEvidence(operation, input, partialExecution, "observed"));
+            }
+            if (resources.snapshot !== undefined &&
+                retained.partialObservation === undefined)
+                retained.retainPartialObservation({
+                    kind: "file-snapshot-hash",
+                    ...resources.snapshot,
+                });
+            result = err(retained);
         }
-        finally {
-            await source?.close().catch(() => undefined);
+        const released = await this.#artifacts.release(owner);
+        const observation = result.ok && (released.kind === "failed" || signal?.aborted === true)
+            ? createAnalysisExecutionEvidence(operation, input, result.value, "observed")
+            : undefined;
+        if (result.ok && signal?.aborted)
+            result = err(new AnalysisCancelledError(operation, {
+                cause: signal.reason,
+                partialObservation: observation,
+            }));
+        if (released.kind === "failed") {
+            const cleanup = new ProviderCleanupError("apktool", [root], {}, {
+                operation,
+                cause: released.cause,
+                ...(observation === undefined
+                    ? {}
+                    : { partialObservation: observation }),
+            });
+            new AnalysisCleanupLeaseGroup(cleanup, [lease]);
+            return err(result.ok
+                ? cleanup
+                : analysisErrorWithCleanupFailure(result.error, cleanup, operation).bindCleanupDependencies([result.error, cleanup]));
         }
+        return result;
     }
 }