Define the disclosure-safe Support bundle data contract

[frankieramirez]

Question

Which diagnostic data may the Support bundle contain, what must be excluded or transformed, and what evidence is sufficient to claim that the resulting archive is safe for the sharing instruction presented to operators?

Resolve the archive manifest, sensitivity classes, redaction guarantees and failure posture, public-versus-private sharing language, and behavior for every supported runtime path configuration.

[frankieramirez]

Resolution

The Support bundle is a versioned, structured diagnostic projection, not a redacted copy of Comicarr's working files.

Sharing contract

The bundle is engineered for attachment to a public issue after mandatory operator review. The archive and UI must tell the operator to inspect it before attaching it; if anything appears sensitive, it is shared privately with maintainers instead. “Engineered for public attachment” is a data-minimization and evidence claim, not a guarantee that removes operator judgment.

Non-negotiable exclusions

The bundle never contains or copies:

• the live database or any database rows;
• config.ini or arbitrary configuration keys or values;
• raw, redacted, or excerpted log lines;
• environment variables or arbitrary subprocess output;
• filesystem paths, basenames, path hashes, hostnames, usernames, endpoints, URLs, proxy values, certificates, SSH material, scripts, or executable locations;
• library titles, issue names, external IDs, release/provider identifiers, torrent hashes, attachment metadata, chat content, AI prompts/results/cache content, payload JSON, tracebacks, exception messages, or other free text;
• exact operational timestamps other than the bundle generation time;
• branch names, Git status, unverified commit/build identifiers, or an unbounded package listing.

Redaction remains defense in depth for permitted values; it is not the admission boundary.

Exact archive manifest

Contract version 1 contains exactly three fixed member names, in a fixed order:

1. README.txt — static disclosure guidance: purpose, intended recipient, mandatory inspection before public attachment, private-sharing fallback, and the contract version. It contains no runtime-derived values.
2. manifest.json — product and contract version, UTC generation time, the exact member inventory with size and digest, source availability using fixed enums, and a machine-readable operator_review_required: true disclosure marker.
3. diagnostics.json — the allowlisted diagnostic projection described below.

The archive filename and ZIP metadata may not be derived from a local path, hostname, username, branch, source filename, or other operator data.

Every JSON schema is closed (additionalProperties: false); new members or fields require an explicit contract-version decision.

Permitted diagnostic projection

diagnostics.json may contain only normalized primitives in these reviewed categories:

• Build: public release/version, verified public build identity when available, and install-method enum; custom/unverified builds are reported only as custom or unverified.
• Runtime: normalized OS family and architecture, Python version, database dialect, a fixed allowlist of dependency versions, and named capability states.
• Configuration: a fixed allowlist of feature booleans, integration-type enums, safe numeric intervals, and configured|not_configured|unknown states. No configured value is emitted.
• Database: connectivity, schema/migration version and state, required-table availability, and explicitly declared aggregate counts. V1 may include numeric series/issue and operational-state counts, but never labels, identifiers, or row content.
• Health: fixed subsystem, scheduler, acquisition, route, and worker state enums; fixed reason codes and aggregate counts only. Free-text detail is prohibited.
• Recency: fixed age buckets such as lt_5m, 5m_30m, 30m_2h, 2h_24h, 1d_7d, gt_7d, and never; exact activity times are prohibited.
• Log-derived facts: bounded counts by fixed severity/subsystem only. No log line or source filename survives.
• Source status: available|unavailable plus a fixed omission reason such as access_denied|parse_failed|unsupported|not_configured.

AI contributes only an enabled/configured state and bounded operational counts under the same fixed enums; model names, content, attachment facts, token history, and error detail remain excluded. Provider and downloader types may be emitted from a fixed enum; custom names, endpoints, IDs, and response detail may not.

Runtime paths and data sources

Collectors resolve sources only from the active runtime context and active database connection, so supported custom config, data, log, and database locations behave like defaults. Paths are internal inputs and are never serialized. An unavailable custom source produces only a fixed unavailable reason; there is no fallback to guessed default files.

Failure posture

• Mandatory contract metadata or final-schema validation failure aborts generation and publishes no archive.
• An unavailable optional source produces a typed unavailable status and an otherwise valid, visibly incomplete bundle.
• A candidate field that cannot be normalized or classified is discarded with its source marked unavailable.
• Any unexpected archive member, JSON key, non-allowlisted value type, size/count bound breach, path-like value, URL-like value, credential-shaped value, or serialization fallback aborts publication.
• No failure path may fall back to copying the legacy database, config, logs, environment, or arbitrary error text.

Evidence required for the disclosure claim

Before the product may ask operators to attach this bundle publicly, implementation evidence must establish:

• an exact, versioned member and field manifest with a sensitivity classification and bound for every emitted field;
• positive schema tests proving the exact closed shape and bounds;
• archive-wide negative tests over filenames, ZIP metadata, and every decompressed byte using seeded credentials, URLs, paths, usernames, hostnames, chat/AI content, payloads, identifiers, and free-text errors;
• fixtures covering every supported database dialect and custom runtime path configuration without emitting those source locations;
• evolution gates proving that new database tables, configuration fields, integrations, or diagnostic sources cannot enter the projection automatically;
• representative generated artifacts reviewed against the public-attachment threat model.

The later verification decision will turn this evidence bar into the detailed acceptance matrix.

Consequence for the legacy generator

The current collect-and-redact carePackage data path cannot satisfy this contract: its raw database, copied config, scrubbed logs, environment dump, source-derived filenames, and hardcoded paths are all prohibited. The generation-contract decision must choose the replacement boundary and lifecycle; it may reuse isolated safe normalization helpers, but it may not retain the legacy broad collector as the source of bundle contents.