{"openapi":"3.1.0","info":{"title":"Quill API","description":"Governed retrieval API for multi-tenant receipt corpora","license":{"name":"MIT OR Apache-2.0","identifier":"MIT OR Apache-2.0"},"version":"1.0.0"},"paths":{"/healthz":{"get":{"tags":["paths"],"operationId":"healthz","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/openapi.json":{"get":{"tags":["paths"],"operationId":"openapi_json","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/readyz":{"get":{"tags":["paths"],"operationId":"readyz","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadyResponse"}}}}}}},"/v1/tenants/{tenant_id}":{"get":{"tags":["paths"],"operationId":"get_tenant","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantSummary"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/activity":{"get":{"tags":["paths"],"operationId":"get_activity","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityFeed"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/blocks/lookup":{"post":{"tags":["paths"],"operationId":"post_block_lookup","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockLookupRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockLookupResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/corpus/debug":{"get":{"tags":["paths"],"operationId":"get_corpus_debug","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorpusDebugResponse"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/credentials/self/request-key":{"put":{"tags":["paths"],"operationId":"put_request_signing_key","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestKeyPutRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestKeyPutResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/family-shortlist":{"post":{"tags":["paths"],"operationId":"post_family_shortlist","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FamilyShortlistResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/library":{"get":{"tags":["paths"],"operationId":"get_library","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryResponse"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/membership/events":{"post":{"tags":["paths"],"operationId":"post_membership_event","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipReplicationRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipReplicationResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/queries":{"post":{"tags":["paths"],"operationId":"post_query","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/receipts/{receipt_id}":{"get":{"tags":["paths"],"operationId":"get_receipt","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}},{"name":"receipt_id","in":"path","description":"Receipt id","required":true,"schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/receipts/{receipt_id}/context":{"get":{"tags":["paths"],"operationId":"get_receipt_context","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}},{"name":"receipt_id","in":"path","description":"Receipt id","required":true,"schema":{"type":"string"}}],"responses":{"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tenants/{tenant_id}/syntheses":{"post":{"tags":["paths"],"operationId":"post_synthesis","parameters":[{"name":"tenant_id","in":"path","description":"Tenant identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesisRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesisResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/trust/keys/{key_id}":{"get":{"tags":["paths"],"operationId":"get_trust_key","parameters":[{"name":"key_id","in":"path","description":"Trust key identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Plain text verifying key"},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}}},"components":{"schemas":{"ActivityFeed":{"type":"object","description":"Activity feed for visible corpus pulse.","required":["queries_today","queries_this_week","last_ingest_at","corpus_size_bytes","recent_queries"],"properties":{"corpus_size_bytes":{"type":"integer","format":"int64","minimum":0},"last_ingest_at":{"type":"string"},"queries_this_week":{"type":"integer","format":"int32","minimum":0},"queries_today":{"type":"integer","format":"int32","minimum":0},"recent_queries":{"type":"array","items":{"$ref":"#/components/schemas/RecentQuery"}}}},"AttestedPart":{"type":"object","description":"One ingested block inside a multi-leaf hit. The joined display quote is not\nitself signed; each part carries the quads for its own UTF-8.","required":["quote","forensics"],"properties":{"forensics":{"$ref":"#/components/schemas/ReceiptForensics"},"quote":{"type":"string"}}},"BlockLookupRequest":{"type":"object","description":"POST `/v1/tenants/{tenant_id}/blocks/lookup` body.\n\nr[impl api.block.get_by_isa]","required":["isa"],"properties":{"corpus_scopes":{"type":"array","items":{"$ref":"#/components/schemas/CorpusScope"},"description":"Role/department prefixes this Get may open (required by handlers)."},"isa":{"type":"string","description":"Canonical `isa_v1:<qid_hex32>:<block_id>:<owner_hex16>`."}}},"BlockLookupResponse":{"type":"object","description":"Lookup envelope: exactly one [`Receipt`] on success.\n\nr[impl contract.block.lookup_envelope]","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Receipt"}}}},"BreakSeam":{"type":"object","description":"Rhetorical seam toward prev or next neighbor.","required":["kind"],"properties":{"kind":{"type":"integer","format":"int32","description":"v2.7 header ordinal `0x00`–`0x1F`.","minimum":0},"phenomenon_id":{"type":["string","null"]},"strength_milli":{"type":["integer","null"],"format":"int32","minimum":0}}},"ContextResponse":{"type":"object","description":"Context snippet for before/after expansion.","required":["receipt_id","text","direction","forensics","verification"],"properties":{"direction":{"type":"string"},"forensics":{"$ref":"#/components/schemas/ReceiptForensics"},"page":{"type":"integer","format":"int32","description":"Printed page of the adjacent chunk (`0` when unknown). Same mapping as `Receipt.page`.","minimum":0},"receipt_id":{"type":"string","description":"Receipt id of the adjacent chunk (frontier for further Contour Reconstruction)."},"text":{"type":"string"},"verification":{"$ref":"#/components/schemas/VerificationEnvelope"}}},"CorpusDebugResponse":{"type":"object","description":"Dev/operator inventory of the corpus prefix this API is actually reading.\nGated by tenant-service signature on the HTTP route, not by DNS_STAGE.","required":["tenant_id","store","bucket","era_fingerprint","prefix","prefix_uri","cob_count","cob_uris","catalog_uris","other_uris"],"properties":{"api_backend_mode":{"type":"string"},"api_build":{"type":"string"},"bounce_at":{"type":["string","null"]},"bucket":{"type":"string"},"catalog_uris":{"type":"array","items":{"type":"string"}},"cob_count":{"type":"integer","minimum":0},"cob_format_id":{"type":["integer","null"],"format":"int32","minimum":0},"cob_uris":{"type":"array","items":{"type":"string"}},"dns_stage":{"type":["string","null"]},"embedding_dimensions_env":{"type":["string","null"]},"embedding_model_id":{"type":["integer","null"],"format":"int32","minimum":0},"encoding_cycle_id":{"type":["integer","null"],"format":"int32","minimum":0},"era_fingerprint":{"type":"string"},"list_error":{"type":["string","null"]},"other_uris":{"type":"array","items":{"type":"string"}},"prefix":{"type":"string"},"prefix_uri":{"type":"string"},"prefix_uris":{"type":"array","items":{"type":"string"},"description":"All live prefixes this process reads (Dynamo list; empty when unconfigured)."},"quantizer_id":{"type":["integer","null"],"format":"int32","minimum":0},"silo_embed_model":{"type":["string","null"]},"silo_embedding_dim":{"type":["integer","null"],"minimum":0},"silo_min_cosine":{"type":["number","null"],"format":"float"},"silo_root_qid_chars":{"type":["integer","null"],"minimum":0},"silo_toml":{"type":["string","null"]},"silo_uri":{"type":["string","null"]},"store":{"type":"string","description":"`s3`, `local`, `mock`, or `none`."},"tenant_id":{"type":"string"}}},"CorpusScope":{"type":"object","description":"One S3 path scope: `{role}/{department}/…` under the tenant bucket.\n\nr[impl contract.corpus.scope_pair]","required":["role","department"],"properties":{"department":{"type":"string"},"role":{"type":"string"}}},"EraKey":{"type":"object","description":"Encoding era metadata (MVP `EraKey`).","required":["encoding_cycle_id","embedding_model_id","quantizer_id","cob_format_id"],"properties":{"cob_format_id":{"type":"integer","format":"int32","minimum":0},"embedding_model_id":{"type":"integer","format":"int32","minimum":0},"encoding_cycle_id":{"type":"integer","format":"int32","minimum":0},"quantizer_id":{"type":"integer","format":"int32","minimum":0}}},"ErrorBody":{"type":"object","description":"Standard error JSON body.","required":["error","status"],"properties":{"error":{"type":"string"},"status":{"type":"integer","format":"int32","minimum":0}}},"FamilyShortlistResponse":{"type":"object","description":"Family-shape shortlist preview (preferred / acceptable / avoided) before retrieval.","required":["query","expected_family_ids","expected_family_names","excluded_family_ids","excluded_family_names"],"properties":{"acceptable_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"acceptable_family_names":{"type":"array","items":{"type":"string"}},"excluded_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Avoided families (`excluded_*` kept for older clients)."},"excluded_family_names":{"type":"array","items":{"type":"string"}},"expected_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Preferred ∪ acceptable (legacy “searched” list)."},"expected_family_names":{"type":"array","items":{"type":"string"}},"preferred_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"preferred_family_names":{"type":"array","items":{"type":"string"}},"query":{"type":"string"},"shortlist_prompt_version":{"type":"string","description":"Prompt revision used for this shortlist (`answer-shape-v1`, etc.)."},"stage_ms":{"type":["integer","null"],"format":"int64","minimum":0}}},"HealthResponse":{"type":"object","description":"Liveness probe.","required":["ok","build"],"properties":{"build":{"type":"string"},"ok":{"type":"boolean"}}},"IsaRef":{"type":"object","description":"Structured live ISA (packed 16-byte QID + block + owner).","required":["qid","block_id","owner_id","canonical"],"properties":{"block_id":{"type":"integer","format":"int32","minimum":0},"canonical":{"type":"string","description":"Canonical copy-paste string."},"owner_id":{"type":"string","description":"Lowercase hex of `u64` owner (`tenant_hi << 32 | watcher_lo` on ingest)."},"qid":{"type":"string","description":"Lowercase hex of packed `[u8; 16]` QID."}}},"LibraryBook":{"type":"object","description":"Flattened library book returned by `GET .../library`.","required":["title"],"properties":{"author":{"type":["string","null"]},"book_id":{"type":["string","null"],"description":"Author Dynamo book id when this row is an author-drop snapshot."},"content_hash":{"type":["string","null"],"description":"64-char lowercase hex of source SHA-256 (snapshot identity; catalog gate hash join)."},"distribution_model":{"type":["string","null"]},"edition":{"type":["string","null"]},"kind":{"type":["string","null"]},"license_note":{"type":["string","null"]},"page_count":{"type":["integer","null"],"format":"int32","description":"Physical PDF page count from notary EOF (`catalog.page_count`).","minimum":0},"page_display_offset":{"type":["integer","null"],"format":"int32","description":"Printed page = mechanical `page_number` + this offset when elected."},"page_offset_elected":{"type":["boolean","null"],"description":"When true, footnotes apply `page_display_offset` to mechanical COB page."},"publication_year":{"type":["integer","null"],"format":"int32","description":"Publication year of the source work (flattened from catalog `book.publication_year`).","minimum":0},"purchase_label":{"type":["string","null"]},"purchase_url":{"type":["string","null"],"description":"Purchase page (Amazon, publisher, or author site). Deserializes legacy `amazon_url`."},"sample_clipboard_percent_90d":{"type":["integer","null"],"format":"int32","description":"Max clipboard export charge as whole-number % of book characters / 90 days.","minimum":0},"sample_pages":{"type":["integer","null"],"format":"int32","description":"Max distinct source pages exposable via search/preview (copyright-holder cap).","minimum":0},"sample_words":{"type":["integer","null"],"format":"int32","description":"Max cumulative quotable words across search/preview (copyright-holder cap).","minimum":0},"source_basename":{"type":["string","null"],"description":"Basename of the source PDF (serve joins hit `source_document_path` → catalog)."},"stored_object_url":{"type":["string","null"]},"title":{"type":"string"},"total_chars":{"type":["integer","null"],"format":"int64","description":"Character count of extracted book text (catalog `total_chars`); clipboard charge denominator.","minimum":0},"translation":{"type":["string","null"]}}},"LibraryResponse":{"type":"object","description":"Unified library response for a tenant.","required":["catalog_version","books"],"properties":{"books":{"type":"array","items":{"$ref":"#/components/schemas/LibraryBook"}},"catalog_version":{"type":"integer","format":"int32","minimum":0},"generated_at":{"type":["string","null"]},"serve_configured":{"type":"boolean","description":"False when Dynamo `corpus-sources` has no URIs and no local path is set.\nDefault true so mock/legacy JSON without the field still looks configured."}}},"MembershipEventDoc":{"type":"object","description":"OpenAPI body for `POST /v1/tenants/{tenant_id}/membership/events`.\nThe live type is `quill_registry::ReplicationRequest`; this schema matches its JSON.","required":["op","credential_id","user_subject","roles","seq","prev_hash","admin_assertion"],"properties":{"admin_assertion":{"type":"string"},"credential_id":{"type":"string"},"op":{"type":"string"},"prev_hash":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"seq":{"type":"integer","format":"int64","minimum":0},"user_subject":{"type":"string"}}},"MembershipReplicationRequest":{"type":"object","required":["event"],"properties":{"event":{"$ref":"#/components/schemas/MembershipEventDoc"}}},"MembershipReplicationResponse":{"type":"object","required":["status","event_hash","seq"],"properties":{"event_hash":{"type":"string"},"seq":{"type":"integer","format":"int64","minimum":0},"status":{"type":"string"}}},"NotaryChainForensics":{"type":"object","description":"Hex-encoded notary hash quads persisted on COB at chunk boundary.","properties":{"bytes_segment_hash":{"type":["string","null"]},"event_content_hash":{"type":["string","null"]},"previous_chain_hash":{"type":["string","null"]},"text_segment_hash":{"type":["string","null"]}}},"PipelineStages":{"type":"object","description":"Structured retrieval pipeline counters returned with query results.","required":["prefixes_loaded","chunks_scanned","chunks_after_rc8_filter","corpus_version"],"properties":{"chunks_after_rc8_filter":{"type":"integer","format":"int32","minimum":0},"chunks_scanned":{"type":"integer","format":"int32","minimum":0},"corpus_version":{"type":"string"},"prefixes_loaded":{"type":"integer","format":"int32","minimum":0}}},"QidBucketProbe":{"type":"object","description":"Per-bucket QID routing probe for live retrieval diagnostics.","required":["stem","volume_resolved","chunks_scanned"],"properties":{"chunks_scanned":{"type":"integer","format":"int32","description":"Chunks scanned in allowed family regions (0 if missing volume or all filtered).","minimum":0},"stem":{"type":"string","description":"Silo-root base32 stem for this NeighborPlan bucket."},"volume_resolved":{"type":"boolean","description":"False when no volume resolved for this bucket (rack NotFound)."}}},"QueryRequest":{"type":"object","description":"Query request body.","properties":{"contour_weight_acceptable":{"type":["number","null"],"format":"float"},"contour_weight_avoided":{"type":["number","null"],"format":"float"},"contour_weight_preferred":{"type":["number","null"],"format":"float","description":"Override silo `contour_weight_preferred` for this query only."},"corpus_roles":{"type":"array","items":{"type":"string"},"description":"Retired IAM ARN list — ignored. Prefer [`Self::corpus_scopes`]."},"corpus_scopes":{"type":"array","items":{"$ref":"#/components/schemas/CorpusScope"},"description":"Role/department prefixes this query may open (required by handlers).\n\nr[impl api.query.corpus_scope_required]"},"family_acceptable":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"family_avoided":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"family_preferred":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Preferred family ids (0..=31). With acceptable+avoided, skips re-inference."},"max_chain":{"type":["integer","null"],"format":"int32","description":"Max length of a chained response, compared to the chunk count stored on\nthe first block (`run_span`). Omitted and `0` do not filter. `1` is\nsingle-chunk mode. `2+` skips a longer chain before cosine.","minimum":0},"min_cosine":{"type":["number","null"],"format":"float","description":"Override silo `min_cosine` for this query only (finite, in `[0, 1]`)."},"q":{"type":"string"},"skip_family_contour":{"type":"boolean","description":"Skip LLM contour partition; every family weight is 1.0 (desk All results)."},"target_families":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Retired include list. Live query returns HTTP 400 when this is set without\nthe three family bucket lists."}}},"QueryResponse":{"type":"object","description":"Query response with receipts and pipeline stages.","required":["query","display_query","pipeline","receipts"],"properties":{"display_query":{"type":"string"},"pipeline":{"$ref":"#/components/schemas/PipelineStages"},"query":{"type":"string"},"receipts":{"type":"array","items":{"$ref":"#/components/schemas/Receipt"}},"search_debug":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SearchDebug","description":"Optional retrieval diagnostics for desk insight / ops (absent on mock paths)."}]}}},"Rc8Plus":{"type":"object","description":"RC8 axis vector plus 32-family rhetorical grammar id (RC8+).","required":["rc8","family_id"],"properties":{"family_id":{"type":"integer","format":"int32","description":"Display-only. Do not rank on this field (`backend.retrieval.family_mask_max_weight`).","minimum":0},"family_mask":{"type":"integer","format":"int32","description":"Chunk `block_rc8_family_mask` (OR of families found in the chunk). Ranking\nuses the **max** weight among set bits, not a single family.","minimum":0},"rc8":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}},"ReadyResponse":{"type":"object","description":"Readiness probe.","required":["ok","mode"],"properties":{"mode":{"type":"string"},"ok":{"type":"boolean"}}},"Receipt":{"type":"object","description":"A verbatim source receipt.","required":["id","work_title","pdf_label","page","quote","score","links","forensics","verification"],"properties":{"attested_parts":{"type":"array","items":{"$ref":"#/components/schemas/AttestedPart"},"description":"Covered leaves when this hit is a `run_span` reconstruction.\nEmpty means `quote` is the single attested text."},"edition":{"type":["string","null"]},"forensics":{"$ref":"#/components/schemas/ReceiptForensics"},"id":{"type":"string"},"links":{"$ref":"#/components/schemas/ReceiptLinks"},"page":{"type":"integer","format":"int32","minimum":0},"pdf_label":{"type":"string"},"quote":{"type":"string"},"score":{"type":"number","format":"float"},"verification":{"$ref":"#/components/schemas/VerificationEnvelope"},"work_title":{"type":"string"}}},"ReceiptForensics":{"type":"object","description":"Provenance and routing metadata for a receipt.","required":["content_sha256","ingested_at","origin","corpus_version","qid_prefix","neighbor_prefixes","volume_file","chunk_index","rc8","rc8_plus","era_key","chain_digest","attestation_signature","verifying_key_id"],"properties":{"attestation_signature":{"type":"string"},"block_rc8_family_mask":{"type":["integer","null"],"format":"int32","description":"Chunk OR-mask of RC8 families found in the chunk.","minimum":0},"block_rc8x_family_mask":{"type":["integer","null"],"format":"int32","minimum":0},"break_next":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BreakSeam","description":"Rhetorical seam toward next neighbor."}]},"break_prev":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BreakSeam","description":"Rhetorical seam toward previous neighbor."}]},"chain_digest":{"type":"string"},"chunk_index":{"type":"integer","format":"int32","minimum":0},"content_crc48":{"type":["string","null"]},"content_sha256":{"type":"string"},"corpus_version":{"type":"string"},"document_next_available":{"type":["boolean","null"],"description":"Later exists only when `next_isa` already passed lookup."},"document_prev_available":{"type":["boolean","null"],"description":"Earlier exists only when `prev_isa` already passed lookup."},"era_key":{"$ref":"#/components/schemas/EraKey"},"expand_disabled_reason":{"type":["string","null"],"description":"Human-readable reason an expand direction is disabled (e.g. copyright sample cap).\nBook-level: both arrows stay off. A single side uses the per-direction fields."},"ingested_at":{"type":"string"},"isa":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IsaRef","description":"This chunk’s live packed ISA (`isa_v1:...`). JSON only; HTML must not render it."}]},"isa_l0_prefix":{"type":["string","null"]},"neighbor_prefixes":{"type":"string"},"next_expand_disabled_reason":{"type":["string","null"],"description":"Later is withheld because the hop would pass the copyright sample cap."},"next_isa":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IsaRef","description":"Next document-chain neighbor ISA when followable."}]},"next_page":{"type":["integer","null"],"format":"int32","description":"Printed page of the verified Later neighbor.","minimum":0},"next_quote_words":{"type":["integer","null"],"format":"int32","description":"Word count of the verified Later neighbor. Present only with `next_isa`.","minimum":0},"notary_chain":{"$ref":"#/components/schemas/NotaryChainForensics","description":"Rolling notary chain quads from ingest (required for live verify)."},"origin":{"type":"string"},"prev_expand_disabled_reason":{"type":["string","null"],"description":"Earlier is withheld because the hop would pass the copyright sample cap."},"prev_isa":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IsaRef","description":"Previous document-chain neighbor ISA when followable."}]},"prev_page":{"type":["integer","null"],"format":"int32","description":"Printed page of the verified Earlier neighbor.","minimum":0},"prev_quote_words":{"type":["integer","null"],"format":"int32","description":"Word count of the verified Earlier neighbor. Present only with `prev_isa`.","minimum":0},"qid_prefix":{"type":"string"},"query_family_mask":{"type":["integer","null"],"format":"int32","description":"Families asked for on this query (`None` on lookup without a shortlist).","minimum":0},"rc8":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"rc8_hint":{"type":["string","null"],"description":"Display-only rhetorical hint; never used in verification (`forensics.rc8.hint_display_only`)."},"rc8_plus":{"$ref":"#/components/schemas/Rc8Plus"},"sentences":{"type":"array","items":{"$ref":"#/components/schemas/SentenceRhetoricForensics"},"description":"Per-sentence spans and contours; empty when the volume omits `sentence_rc8_pack`."},"terminal_source_hash":{"type":["string","null"]},"verifying_key_id":{"type":"string"},"volume_chunk_count":{"type":["integer","null"],"format":"int32","description":"Chunks in this COB volume when known (live serve). Silo length — not end-of-book.","minimum":0},"volume_file":{"type":"string"}}},"ReceiptLinks":{"type":"object","description":"Retail / reader links for a receipt.","required":["view_url"],"properties":{"purchase_label":{"type":["string","null"],"description":"Optional CTA label override (e.g. \"Buy on Amazon\", \"Buy from author\")."},"purchase_url":{"type":["string","null"],"description":"Purchase page (Amazon, publisher, or author site). Deserializes legacy `amazon_url`."},"stored_object_url":{"type":["string","null"]},"view_url":{"type":"string"}}},"RecentQuery":{"type":"object","description":"A single recent query entry.","required":["q","at"],"properties":{"at":{"type":"string"},"q":{"type":"string"}}},"RequestKeyPutRequest":{"type":"object","description":"Mode A request-signing pubkey rotation (self-service).","required":["request_signing_pubkey","expires_at"],"properties":{"expires_at":{"type":"integer","format":"int64"},"request_signing_pubkey":{"type":"string"}}},"RequestKeyPutResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}}},"SearchDebug":{"type":"object","description":"Live-path retrieval diagnostics attached to [`QueryResponse`].","required":["retrieval_mode","target_family_ids","target_family_names","stage_ms"],"properties":{"acceptable_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"acceptable_family_names":{"type":"array","items":{"type":"string"}},"contour_weight_acceptable":{"type":"number","format":"float"},"contour_weight_avoided":{"type":"number","format":"float"},"contour_weight_preferred":{"type":"number","format":"float","description":"Effective contour multipliers used to rank this query."},"excluded_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Avoided families (`excluded_*` kept for older clients)."},"excluded_family_names":{"type":"array","items":{"type":"string"}},"hits_dropped_below_min_cosine":{"type":"integer","format":"int32","description":"Hits dropped because `score < min_cosine` (0 when paste skip or none dropped).","minimum":0},"min_cosine":{"type":"number","format":"float","description":"Serve cosine floor applied after merge (`cob-silo.toml` `min_cosine`)."},"neighbor_qid_stems":{"type":"array","items":{"type":"string"},"description":"NeighborPlan expansion stems (excluding primary)."},"preferred_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"preferred_family_names":{"type":"array","items":{"type":"string"}},"primary_qid_stem":{"type":"string","description":"Query primary QID stem at silo root width."},"qid_probes":{"type":"array","items":{"$ref":"#/components/schemas/QidBucketProbe"},"description":"Ordered bucket probes from NeighborPlan walk."},"query_family_mask":{"type":"integer","format":"int32","description":"Bits actually searched (`u32::MAX` when contour weights apply).","minimum":0},"request_id":{"type":["string","null"]},"retrieval_mode":{"type":"string","description":"`\"embedded\"` (in-process S3 rack) or `\"picker\"` (remote Cob Picker)."},"shortlist_prompt_version":{"type":"string","description":"Family shortlist prompt revision (empty when contour skipped or client-supplied buckets)."},"stage_ms":{"$ref":"#/components/schemas/SearchStageMs"},"target_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0},"description":"Preferred ∪ acceptable family ids (diagnostics; not the scan mask)."},"target_family_names":{"type":"array","items":{"type":"string"}}}},"SearchStageMs":{"type":"object","description":"Per-stage wall-clock timings for a live query (milliseconds).","properties":{"embed":{"type":["integer","null"],"format":"int64","minimum":0},"family_shortlist":{"type":["integer","null"],"format":"int64","minimum":0},"retrieval":{"type":["integer","null"],"format":"int64","minimum":0}}},"SentenceRhetoricForensics":{"type":"object","description":"Per-sentence RC8/RC8x span inside a chunk (UTF-8 offsets into receipt quote text).","required":["ordinal","byte_start","byte_end","rc8","matches_query"],"properties":{"byte_end":{"type":"integer","format":"int32","minimum":0},"byte_start":{"type":"integer","format":"int32","minimum":0},"matches_query":{"type":"boolean"},"ordinal":{"type":"integer","format":"int32","minimum":0},"rc8":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"rc8_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}},"rc8x":{"type":["array","null"],"items":{"type":"integer","format":"int32","minimum":0}},"rc8x_family_ids":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}},"SynthesisRequest":{"type":"object","description":"Synthesis request.","properties":{"receipt_ids":{"type":"array","items":{"type":"string"}}}},"SynthesisResponse":{"type":"object","description":"Synthesis response (mock phase — optional generated prose).","required":["cited_receipt_ids","titles","message","is_machine_generated"],"properties":{"cited_receipt_ids":{"type":"array","items":{"type":"string"}},"generated_text":{"type":["string","null"]},"is_machine_generated":{"type":"boolean"},"message":{"type":"string"},"model_id":{"type":["string","null"]},"titles":{"type":"array","items":{"type":"string"}}}},"TenantSummary":{"type":"object","description":"Tenant metadata summary.","required":["tenant_id","display_name","badge","corpus_version"],"properties":{"badge":{"type":"string"},"corpus_version":{"type":"string"},"display_name":{"type":"string"},"tenant_id":{"type":"string"}}},"VerificationCheck":{"type":"object","required":["name","passed"],"properties":{"name":{"type":"string"},"passed":{"type":"boolean"}}},"VerificationEnvelope":{"type":"object","required":["status","checks"],"properties":{"checks":{"type":"array","items":{"$ref":"#/components/schemas/VerificationCheck"}},"status":{"$ref":"#/components/schemas/VerificationStatus"}}},"VerificationStatus":{"type":"string","description":"Verification outcome for a verbatim text slice.","enum":["passed","failed"]}}},"tags":[{"name":"quill","description":"Quill governed retrieval API"}]}