Lock the exact Support bundle v1 contract assets

[frankieramirez]

Question

What are the exact, byte- and field-level contents of the Support bundle v1 contract assets that the locked architecture specification and implementation must use?

Lock all remaining content decisions together:

• the complete manifest.schema.json, including fixed member inventory, non-circular digest rules, source records, status consistency, formats, enums, and bounds;
• the complete diagnostics.schema.json, with every emitted field, exact type, enum, collection/cardinality/numeric/string bound, required/optional rule, and no unspecified category left to the implementer;
• the matching field-manifest.json, including meaning, source authority, sensitivity classification, and complete/partial behavior for every schema path;
• the exact static bytes of README.txt;
• the exact dependency allowlist, provider/downloader/install/capability/health/recency/source/reason enums, safe aggregates, and normalization rules;
• the fixed HTTP error detail sentences and any exact UI/documentation copy not already locked; and
• fixtures demonstrating one complete and one partial v1 object without introducing identifiers, paths, URLs, free text, or other prohibited data.

Stress-test usefulness against disclosure minimization: a field enters v1 only when it materially helps diagnose Comicarr and can be normalized into the closed contract. Omit speculative fields instead of reserving them.

Settled input

• Define the disclosure-safe Support bundle data contract
• Choose the Support bundle generation and download contract
• Specify the Settings Support bundle interaction
• Lock the Support bundle security and acceptance contract
• Choose the canonical Support bundle specification and implementation handoff

This remains planning only. Resolve exact contract content; do not implement the generator, endpoint, UI, CI, or documentation activation.

[frankieramirez]

Resolution

Support bundle contract v1 is deliberately small. It reports public build/runtime facts, a fixed set of configured-state facts, bounded library/work aggregates, and normalized health. It does not reserve speculative fields and does not parse log text. Every emitted string is a constant, a closed enum, a normalized numeric release, a UTC generation timestamp, or a SHA-256 digest.

This resolution is the exact content source for the future v1/ assets. Implementers may transcribe it into JSON Schema and fixtures but may not choose additional fields, enums, dependencies, bounds, or copy.

Encoding and deterministic bytes

• README.txt: UTF-8 without BOM, LF line endings, exactly the bytes in the block below, including its final newline.
• JSON: UTF-8 without BOM; json.dumps(value, ensure_ascii=True, allow_nan=False, sort_keys=True, separators=(",", ":")) + "\n".
• JSON duplicate keys, NaN, positive/negative infinity, non-UTF-8, comments, trailing data, and a missing final LF fail validation.
• ZIP order remains README.txt, manifest.json, diagnostics.json. Member paths, comments, extras, permissions, timestamps, creator system, and compression settings are fixed by the architecture spec and never source-derived.

Exact README.txt

Comicarr Support bundle
Contract version 1

This archive is intended for Comicarr maintainers helping troubleshoot Comicarr.
It contains only allowlisted diagnostic facts. It is not a copy of your database
or settings file and does not include settings values, raw log lines, library
names, paths, chat content, or other free text. It may include normalized
configuration states and bounded aggregate count buckets.

Before sharing
1. Review README.txt, manifest.json, and diagnostics.json.
2. Attach this archive to a public issue only if you are comfortable with every value.
3. If anything appears sensitive, share it privately with a maintainer instead.

manifest.json describes the contract, archive members, and source availability.
diagnostics.json contains the versioned diagnostic projection.

Operator review is required. This archive is engineered for public issue attachment
after review; it is not a guarantee that every value is appropriate to share.

The encoded file is 965 bytes and its SHA-256 is 7a568b84ac627e0f5504d15d407ae550e841241efd11a17db1250022c7ff1ae7.

Shared schema rules

Both schemas use JSON Schema draft 2020-12. Their exact $id values are urn:comicarr:support-bundle:manifest:1 and urn:comicarr:support-bundle:diagnostics:1; they use only same-document $ref values and perform no network lookup. Every object sets additionalProperties: false. Every property shown below is required unless explicitly marked optional. Arrays use prefixItems or closed item schemas plus minItems/maxItems; unevaluatedItems is false. Regex validation uses ASCII semantics.

Shared scalar definitions:

Name	Exact contract
normalized_version	unknown or three decimal components, each 0–65535, rendered without leading zeroes except 0; maximum 17 bytes
utc_second	real UTC instant formatted exactly YYYY-MM-DDTHH:MM:SSZ; year 2000–9999; no fractional seconds or offset form
sha256	exactly 64 lowercase hexadecimal characters
count_bucket	zero, one, 2_9, 10_99, 100_999, 1k_9k, 10k_99k, or 100k_plus
availability	available or unavailable
unavailable_reason	access_denied, query_failed, schema_unavailable, dependency_unavailable, or unsupported
toggle_state	enabled, disabled, or unknown
integration_state	configured, not_configured, disabled, or unknown
recency	lt_5m, 5m_30m, 30m_2h, 2h_24h, 1d_7d, gt_7d, never, or unknown

The count buckets map nonnegative integers exactly as follows: zero = 0; one = 1; 2_9 = 2–9; 10_99 = 10–99; 100_999 = 100–999; 1k_9k = 1,000–9,999; 10k_99k = 10,000–99,999; and 100k_plus = 100,000 or greater.

unknown is an explicit normalized fact, not a substitute for collector failure. A source that cannot safely collect its required object is unavailable and follows the partial-bundle rule.

Complete manifest.schema.json contract

The root has exactly these required properties:

Property	Exact type/value
contract_version	integer, const: 1
product	string, const: "Comicarr"
product_version	normalized_version
generated_at	utc_second
bundle_status	complete or partial
operator_review_required	boolean, const: true
members	the fixed three-entry tuple below
sources	the fixed five-source object below

members is exactly three objects in this order:

1. {"name":"README.txt","size_bytes":<1..16384>,"sha256":<sha256>}
2. {"name":"manifest.json"}
3. {"name":"diagnostics.json","size_bytes":<1..262144>,"sha256":<sha256>}

Each member object is closed. The manifest entry intentionally carries neither its own digest nor its own size: both are self-referential. It is protected by closed-schema validation, fixed name/order, canonical bytes, response length, and archive bounds. The two payload entries must equal the final decompressed bytes. No media type, compressed size, ZIP offset, CRC, or archive digest is emitted.

sources is a closed object with exactly build, runtime, configuration, database, and health:

• build, runtime, and configuration are mandatory source objects exactly equal to {"status":"available"}. Failure to obtain them aborts generation.
• database and health are each either {"status":"available"} or {"status":"unavailable","reason":<unavailable_reason>}.

Cross-document validation, after both schemas pass, enforces:

1. bundle_status == "complete" iff both optional sources are available; otherwise it is partial.
2. diagnostics.database is present iff sources.database.status == "available".
3. diagnostics.health is present iff sources.health.status == "available".
4. When database is unavailable, health may be unavailable only as dependency_unavailable unless an independent safe health projection completed; v1's normal implementation marks it dependency-unavailable.
5. product_version == diagnostics.build.release_version.
6. The manifest timestamp is the one captured generation instant used for all recency buckets.
7. Member sizes/digests match the canonical payload bytes, and the settled per-member, total-uncompressed, and final-ZIP limits all pass.

The collector copies only allowlisted primitive inputs into one immutable runtime/config snapshot while holding the existing runtime lock, then releases it. All database-derived diagnostic and health facts use one read transaction/connection. This is the single captured authority; no later reread can mix generations or observe a different configuration.

Complete diagnostics.schema.json contract

The root has required closed objects build, runtime, and configuration. database and health are the only optional properties, governed by the manifest invariants above.

build

Property	Exact type/value	Authority and normalization
release_version	normalized_version	get_release_version(); accept only a plain public numeric release, emit its first three release components while padding missing components with zero, and map prerelease, development, local/build-labelled, invalid, or missing values to unknown
identity	verified_release, custom, or unverified	use the existing local build authority without network/Git work: when its verified flag is true and its declared build id is exactly release_version or v<release_version>, emit verified_release; when verified is true but the id differs, emit custom; otherwise emit unverified; no id/commit value is serialized
install_method	docker, source, package, or unknown	runtime docker → docker; git/source → source; win or an installed wheel/package authority → package; everything else → unknown

Branch, commit, dirty state, repository location, tag text, build hostname, and unverified identity strings are never emitted.

runtime

Property	Exact type/value	Authority and normalization
os_family	linux, windows, macos, bsd, other, or unknown	platform.system() mapped case-insensitively; Darwin → macos; names ending in BSD → bsd; a nonempty unmatched value → other
architecture	x86_64, x86, arm64, arm, other, or unknown	platform.machine() aliases: amd64/x86_64; i386–i686/x86; aarch64/arm64; arm*/arm; nonempty unmatched → other
python_version	normalized_version	sys.version_info[:3]; never platform.python_build() or compiler text
database_dialect	sqlite, postgresql, mysql, or unknown	active SQLAlchemy engine dialect only; driver, URL, host, database name, and credentials are excluded
dependencies	the exact six-key object below	installed distribution metadata normalized only when it is a plain public release; prerelease, development, local/build-labelled, invalid, or missing values become unknown rather than masquerading as the corresponding public release

dependencies contains exactly: apscheduler, fastapi, sqlalchemy, starlette, urllib3, and uvicorn. No transitive package, plugin, editable path, installer metadata, or unbounded package list enters v1.

configuration

The source is the active AppContext.config object only. It never reopens config.ini, follows a configured path, or guesses a default file. Every object is closed.

automation contains exactly three toggle_state values:

• post_processing: POST_PROCESSING boolean;
• rss: ENABLE_RSS boolean;
• update_checks: CHECK_GITHUB boolean.

integrations contains exactly five integration_state values:

• comicvine: disabled when COMICVINE_ENABLED is false; configured when enabled and COMICVINE_API is present; otherwise not_configured;
• metron: disabled when USE_METRON_SEARCH is false; configured when enabled and both username and password are present; otherwise not_configured;
• mangadex: configured when MANGADEX_ENABLED is true, otherwise disabled;
• myanimelist: disabled when MAL_ENABLED is false; configured when enabled and MAL_CLIENT_ID is present; otherwise not_configured;
• ai: configured only when base URL, API key, and model are all present; otherwise not_configured.

An absent config authority yields unknown; the configured values themselves are never serialized.

acquisition contains exactly ddl, nzb, and torrent. Each is a closed object with:

• enabled: toggle_state, derived by the existing effective-route enablement rules; and
• client: one of the route-specific enums below, derived from the active numeric downloader choice without reading its endpoint/path/credentials.

Client enums:

• DDL: local, disabled, unknown (local when DDL is selected; disabled when the route is disabled).
• NZB: sabnzbd, nzbget, blackhole, disabled, unknown from NZB_DOWNLOADER 0/1/2/3/other.
• Torrent: watchfolder, utorrent, rtorrent, transmission, deluge, qbittorrent, disabled, unknown from TORRENT_DOWNLOADER 0–5; disabled only when torrent acquisition is explicitly disabled, while a selected client may still be reported for a disabled route.

No provider names/types, configured provider counts, labels, categories, endpoints, proxy state, script state, intervals, language/content preferences, or path-readiness values appear under configuration.

Optional database

The source is one bounded read transaction/connection on the active SQLAlchemy engine, shared with all health queries so the bundle observes one database snapshot. The object has exactly acquisition_schema_state, acquisition_schema_version, and optional count_buckets.

• acquisition_schema_state: ready, not_ready, or unknown, derived only from the acquisition-maintenance schema authority; Alembic revision text and generic database classification are not emitted.
• acquisition_schema_version: integer 0–65535; 0 means no recognized acquisition schema version. The current value is 7, but the numeric bound allows later compatible schema migrations without changing this disclosure contract.
• count_buckets: present iff acquisition_schema_state == "ready"; otherwise absent. It is a closed object of six count_bucket values:
  • series: all Series rows;
  • issues: all standard Issue rows;
  • annuals: all Annual rows;
  • wanted: standard Issues plus Annuals whose authoritative status is Wanted;
  • in_flight: authoritative accepted/running acquisition items plus open pipeline-journal stages;
  • recovery_pending: the in-flight acquisition-item subset with recovery count greater than zero; never added to in_flight;

Each aggregate is bucketed after one fixed SQL count; exact counts never enter the normalized object. recovery_pending retains its semantic meaning as a subset of in_flight, but buckets are not compared as exact numbers. The unbounded Python grouping used for the UI's needs-attention count is deliberately excluded from v1.

All queries are fixed aggregates. No grouping key, row sample, label, identifier, status breakdown, publisher, content type, issue number, title, or exact database revision is emitted. Every nonnegative raw count maps to exactly one bucket, so a large valid library never loses its Support bundle to numeric overflow.

Optional health

The source is the active config plus the same captured database authority used above. It reuses health predicates but builds a new closed projection; it never serializes existing health response dictionaries wholesale.

The object contains exactly:

Property	Exact shape
overall	healthy, degraded, blocked, or unknown
maintenance	clear, blocked, or unknown
viable_route	boolean
search_worker	healthy, stale, failed, stopped, or unknown
scheduler	fixed search, rss, weekly, import_scan keys, each running, waiting, paused, failed, stopped, or unknown
routes	fixed ddl, nzb, torrent route objects below

Each route has exactly:

• state: ready, disabled, maintenance_blocked, client_not_ready, path_not_ready, providers_blocked, restart_unsafe, or unknown;
• last_success_age: recency.

Normalization:

• route ready stays ready; settled internal reasons map to the corresponding enum (providers_temporarily_blocked → providers_blocked, unsupported_restart_correlation → restart_unsafe); any maintenance reason becomes maintenance_blocked; all other/non-enum text becomes unknown;
• no provider name or count, worker/job name, raw status, error, reason text, owner, run id, lease, timestamp, or traceback survives;
• search-worker state uses the durable heartbeat: a fresh live nonfailed worker is healthy, a known old heartbeat is stale, explicit failed/stopped map directly, and absence/malformed state is unknown;
• scheduler strings normalize case-insensitively: Running → running; Waiting/Queued → waiting; Paused → paused; Error/Failed/Missed/Max instances → failed; Stopped/Shutdown → stopped; anything else → unknown;
• recency is age from the captured generation instant: [0,300) seconds → lt_5m; [300,1800) → 5m_30m; [1800,7200) → 30m_2h; [7200,86400) → 2h_24h; [86400,604800) → 1d_7d; >=604800 → gt_7d; no recorded success → never; malformed/nonfinite or more than 60 seconds in the future → unknown; a future skew of at most 60 seconds clamps to age zero;
• overall is blocked when maintenance is blocked or no viable route exists; healthy requires maintenance clear, a viable route, a healthy search worker, and no enabled route in a nonready state; degraded means a viable route exists but one of those nonfatal conditions fails; otherwise unknown.

Exact field-manifest classifications

field-manifest.json is a closed root object with exactly contract_version: 1 and a fields array. Every entry represents one scalar leaf, uses an exact RFC 6901 pointer, and is a closed object with these keys always present: schema (manifest or diagnostics), pointer, source, classification, availability, json_type, const, enum, pattern, minimum, maximum, max_bytes, and meaning. Inapplicable constraint values are JSON null; enum is either null or a nonempty unique scalar array. meaning is the exact definition already given in this resolution, limited to 240 UTF-8 bytes. These records are contract documentation and are never copied into the bundle. Entries are unique by (schema,pointer) and sorted first by schema, then by pointer, using Unicode code-point order.

source is closed to contract_asset, clock, build_authority, process_metadata, distribution_metadata, active_config, active_engine, acquisition_schema, aggregate_query, health_projection, archive_validator, and collector_coordinator. classification is closed to the classifications in the table below. availability is mandatory, optional_database, optional_database_ready, optional_health, or unavailable_only. json_type is string, integer, or boolean. The remaining constraint columns exactly mirror the referenced scalar node in the corresponding schema; parity validation expands both schemas to scalar leaves and requires a one-to-one match.

The array contains one entry for every leaf or closed repeated family below; brace notation denotes all named leaves, not a wildcard:

Paths	Source	Classification	Availability
manifest.contract_version, manifest.product, manifest.operator_review_required	contract asset	disclosure_contract	mandatory
manifest.product_version, diagnostics.build.{release_version,identity,install_method}	verified local build metadata	public_build	mandatory
manifest.generated_at	injected UTC clock	coarse_runtime	mandatory
/bundle_status; /sources/{build,runtime,configuration,database,health}/status; /sources/{database,health}/reason only	collector coordinator	operational_state	status mandatory; reason unavailable_only
manifest.members.README.txt.{name,size_bytes,sha256}, manifest.members.manifest.json.name, manifest.members.diagnostics.json.{name,size_bytes,sha256}	final archive validator	integrity	mandatory
diagnostics.runtime.{os_family,architecture,python_version,database_dialect}	normalized process/engine metadata	coarse_runtime	mandatory
diagnostics.runtime.dependencies.{apscheduler,fastapi,sqlalchemy,starlette,urllib3,uvicorn}	installed distribution metadata	public_dependency	mandatory
diagnostics.configuration.automation.{post_processing,rss,update_checks}	active config booleans	configuration_state	mandatory
diagnostics.configuration.integrations.{comicvine,metron,mangadex,myanimelist,ai}	presence tests over active config	configuration_state	mandatory
diagnostics.configuration.acquisition.{ddl,nzb,torrent}.{enabled,client}	effective route/config enums	configuration_state	mandatory
diagnostics.database.{acquisition_schema_state,acquisition_schema_version}	acquisition-maintenance schema authority	coarse_database	optional_database
diagnostics.database.count_buckets.{series,issues,annuals,wanted,in_flight,recovery_pending}	fixed aggregate queries followed by count bucketing	aggregate_bucket	optional_database_ready
diagnostics.health.{overall,maintenance,viable_route,search_worker}	normalized health projection	operational_state	optional_health
diagnostics.health.scheduler.{search,rss,weekly,import_scan}	normalized scheduler state	operational_state	optional_health
diagnostics.health.routes.{ddl,nzb,torrent}.{state,last_success_age}	normalized route health	operational_state	optional_health

The table uses braces only to keep this comment readable. The asset contains no brace or wildcard pointer: it expands every named choice into a separate RFC 6901 record (including /members/0/name, /members/0/size_bytes, /members/0/sha256, /members/1/name, /members/2/name, /members/2/size_bytes, and /members/2/sha256). Schema/manifest parity fails if the expanded leaf set differs in either direction or if any type/const/enum/pattern/bound differs.

Exact semantic fixtures

The required complete diagnostics.json fixture is the canonical one-line JSON below (shown wrapped only by the Markdown renderer):

{"build":{"identity":"unverified","install_method":"docker","release_version":"0.27.0"},"configuration":{"acquisition":{"ddl":{"client":"local","enabled":"enabled"},"nzb":{"client":"sabnzbd","enabled":"enabled"},"torrent":{"client":"disabled","enabled":"disabled"}},"automation":{"post_processing":"enabled","rss":"enabled","update_checks":"enabled"},"integrations":{"ai":"not_configured","comicvine":"configured","mangadex":"configured","metron":"disabled","myanimelist":"disabled"}},"database":{"acquisition_schema_state":"ready","acquisition_schema_version":7,"count_buckets":{"annuals":"10_99","in_flight":"2_9","issues":"1k_9k","recovery_pending":"one","series":"100_999","wanted":"10_99"}},"health":{"maintenance":"clear","overall":"healthy","routes":{"ddl":{"last_success_age":"30m_2h","state":"ready"},"nzb":{"last_success_age":"lt_5m","state":"ready"},"torrent":{"last_success_age":"never","state":"disabled"}},"scheduler":{"import_scan":"waiting","rss":"waiting","search":"waiting","weekly":"waiting"},"search_worker":"healthy","viable_route":true},"runtime":{"architecture":"x86_64","database_dialect":"sqlite","dependencies":{"apscheduler":"3.11.0","fastapi":"0.115.0","sqlalchemy":"2.0.42","starlette":"0.46.2","urllib3":"2.7.0","uvicorn":"0.34.0"},"os_family":"linux","python_version":"3.12.4"}}

It is 1,310 bytes including LF and has SHA-256 7d9de3ea15a1b5601426d96529240a79c579c98b90a1b13648af6ee781d73eeb. Its exact manifest fixture is:

{"bundle_status":"complete","contract_version":1,"generated_at":"2026-08-09T12:00:00Z","members":[{"name":"README.txt","sha256":"7a568b84ac627e0f5504d15d407ae550e841241efd11a17db1250022c7ff1ae7","size_bytes":965},{"name":"manifest.json"},{"name":"diagnostics.json","sha256":"7d9de3ea15a1b5601426d96529240a79c579c98b90a1b13648af6ee781d73eeb","size_bytes":1310}],"operator_review_required":true,"product":"Comicarr","product_version":"0.27.0","sources":{"build":{"status":"available"},"configuration":{"status":"available"},"database":{"status":"available"},"health":{"status":"available"},"runtime":{"status":"available"}}}

The required partial fixture omits both optional objects and is:

{"build":{"identity":"unverified","install_method":"docker","release_version":"0.27.0"},"configuration":{"acquisition":{"ddl":{"client":"local","enabled":"enabled"},"nzb":{"client":"sabnzbd","enabled":"enabled"},"torrent":{"client":"disabled","enabled":"disabled"}},"automation":{"post_processing":"enabled","rss":"enabled","update_checks":"enabled"},"integrations":{"ai":"not_configured","comicvine":"configured","mangadex":"configured","metron":"disabled","myanimelist":"disabled"}},"runtime":{"architecture":"x86_64","database_dialect":"sqlite","dependencies":{"apscheduler":"3.11.0","fastapi":"0.115.0","sqlalchemy":"2.0.42","starlette":"0.46.2","urllib3":"2.7.0","uvicorn":"0.34.0"},"os_family":"linux","python_version":"3.12.4"}}

It is 736 bytes including LF and has SHA-256 e25df55d5fa9a8a1cc6fb1116bbcc14e140b4ee1a3cf0401ca33930e7aa19255. Its exact manifest fixture is:

{"bundle_status":"partial","contract_version":1,"generated_at":"2026-08-09T12:00:00Z","members":[{"name":"README.txt","sha256":"7a568b84ac627e0f5504d15d407ae550e841241efd11a17db1250022c7ff1ae7","size_bytes":965},{"name":"manifest.json"},{"name":"diagnostics.json","sha256":"e25df55d5fa9a8a1cc6fb1116bbcc14e140b4ee1a3cf0401ca33930e7aa19255","size_bytes":736}],"operator_review_required":true,"product":"Comicarr","product_version":"0.27.0","sources":{"build":{"status":"available"},"configuration":{"status":"available"},"database":{"reason":"query_failed","status":"unavailable"},"health":{"reason":"dependency_unavailable","status":"unavailable"},"runtime":{"status":"available"}}}

Fixtures contain synthetic aggregates only and no source-derived identifiers.

Fixed HTTP error details

The already-settled codes/statuses/retryability use these exact safe detail strings:

Code	Exact detail
support_bundle_in_progress	Another support bundle is already being created. Try again in a moment.
support_bundle_unavailable	Support bundle generation is temporarily unavailable. Try again later.
support_bundle_validation_failed	Comicarr stopped the download because the bundle did not pass its safety checks. No file was downloaded.
support_bundle_generation_failed	Comicarr could not create the support bundle. Try again.

Authentication and CSRF retain their existing framework bodies; the frontend maps their statuses to the exact copy already settled. No server detail contains exception text, source names, paths, or operator data.

Deliberate v1 omissions

V1 emits no log-derived facts, provider types/names/counts, notifier states, interval values, path-readiness booleans under configuration, AI counts, dependency list beyond the six fixed keys, issue/series status breakdowns, exact operational timestamps, or arbitrary capability map. Log parsing was rejected because its benefit does not justify admitting free-text input into the public-attachment boundary; route/worker/scheduler states and aggregate buckets answer the actionable questions safely. Future usefulness claims must earn a new integer contract version and security review.

The combination of coarse OS/architecture, normalized versions, integration states, route clients, and count buckets can still distinguish an unusual installation. That residual fingerprinting is accepted because each fact has concrete diagnostic value, exact values/identifiers are excluded, and the mandatory README/UI review remains part of the disclosure boundary. It is explicitly covered by the human artifact review rather than described as anonymous telemetry.

Completion consequence

Together with the five earlier decisions, this closes every product, data, lifecycle, UI, security, schema, copy, versioning, and handoff choice needed before implementation. The implementation handoff may transcribe these assets and tests; it may not reinterpret them. No new domain term emerged, so the existing CONTEXT.md Support bundle definition remains sufficient and no ADR is added.