@squidcloud/client 1.0.492 → 1.0.493

package/dist/internal-common/src/types/ai-knowledge-base.types.d.ts

@@ -0,0 +1,514 @@
+import { AiEmbeddingsModelWithOptionalFields, AiKnowledgeBase, AiKnowledgeBaseChatOptions, AiKnowledgeBaseContext, AiKnowledgeBaseContextRequest, AiKnowledgeBaseGraphContext, AiKnowledgeBaseGraphSearchOptions, AiKnowledgeBaseSearchResultChunk } from '../public-types/ai-knowledge-base.public-types';
+import { AiContextId, AiKnowledgeBaseId, AppId } from '../public-types/communication.public-types';
+import { DocumentExtractionMethod } from '../public-types/extraction.public-types';
+/**
+ * Internal (eval-harness-only) extension of the public graph search options. `graphOnly` returns just the
+ * graph channel's chunks (measures the graph's marginal recall) instead of the public `fused` behavior;
+ * it is not exposed in public-types because production callers always fuse. The graph channel accepts
+ * this shape at runtime, so eval specs cast their options to it. Themes-level "global" answering is NOT a
+ * search mode — it moved to the `globalSummary` op of `queryKnowledgeGraph`.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphSearchOptionsInternal extends AiKnowledgeBaseGraphSearchOptions {
+    /** Internal/eval-only: `'graphOnly'` returns only the graph channel; `'fused'` (default) RRF-merges with hybrid. */
+    mode?: 'graphOnly' | 'fused';
+}
+/**
+ * Request structure for getting an AiKnowledgeBase
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseRequest {
+    /** The id of the app */
+    appId: AppId;
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Request structure for getting all AiKnowledgeBases
+ * @category AI
+ */
+export interface GetAiKnowledgeBasesRequest {
+    /** The id of the app */
+    appId: AppId;
+}
+/**
+ * Response structure for getting an AiKnowledgeBase
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseResponse {
+    /** The resulting AiKnowledgeBase, if it is found */
+    knowledgeBase: AiKnowledgeBase | undefined;
+}
+/**
+ * Request structure for deleting an AiKnowledgeBase
+ * @category AI
+ */
+export interface DeleteAiKnowledgeBaseRequest {
+    /** The id of the AiKnowledgeBase */
+    id: string;
+}
+/**
+ * Request structure for upserting an AiKnowledgeBase
+ * @category AI
+ */
+export interface UpsertAiKnowledgeBaseRequest {
+    /** The AiKnowledgeBase to upsert */
+    knowledgeBase: Omit<AiEmbeddingsModelWithOptionalFields, 'appId' | 'updatedAt'>;
+}
+/**
+ * Response structure for listing AiKnowledgeBases
+ * @category AI
+ */
+export interface ListAiKnowledgeBasesResponse {
+    /** The list of AiKnowledgeBases */
+    knowledgeBases: Array<AiKnowledgeBase>;
+}
+/**
+ * Request structure for listing AiKnowledgeBaseContexts
+ * @category AI
+ * @deprecated Fetches every context in one call with no pagination — expensive for large knowledge
+ * bases. Use {@link ListAiKnowledgeBaseContextsPageRequest} instead.
+ */
+export interface ListAiKnowledgeBaseContextsRequest {
+    /** The id of the AiKnowledgeBase */
+    id: string;
+    /** The number of characters after which text is truncated. Optional */
+    truncateTextAfter?: number;
+}
+/**
+ * Response structure to list AiKnowledgeBaseContexts
+ * @category AI
+ * @deprecated See {@link ListAiKnowledgeBaseContextsRequest}.
+ */
+export interface ListAiKnowledgeBaseContextsResponse {
+    /** The list of AiKnowledgeBaseContexts */
+    contexts: Array<AiKnowledgeBaseContext>;
+}
+/**
+ * Response structure to list contextids for an AiKnowledgeBase
+ * @category AI
+ */
+export interface ListAiKnowledgeBaseContextIdsResponse {
+    /** The list of AiContextIds */
+    contextIds: Array<AiContextId>;
+}
+/**
+ * Request structure for deleting AiKnowledgeBaseContexts
+ * @category AI
+ */
+export interface DeleteAiKnowledgeBaseContextsRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** An array of AiKnowledgeBaseContext ids */
+    contextIds: Array<string>;
+}
+/**
+ * Request structure for replacing the access scopes of a single AiKnowledgeBaseContext.
+ * @category AI
+ */
+export interface SetAiKnowledgeBaseContextScopesRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** The id of the AiKnowledgeBaseContext whose scopes are replaced */
+    contextId: string;
+    /** The scopes that grant read access to this context. An empty array makes it visible to everyone. */
+    scopes: Array<string>;
+}
+/**
+ * Response structure for replacing the access scopes of a single AiKnowledgeBaseContext.
+ * @category AI
+ */
+export interface SetAiKnowledgeBaseContextScopesResponse {
+    /** How many chunks of the context had their scopes rewritten. */
+    updatedChunkCount: number;
+}
+/**
+ * Request structure for getting an AiKnowledgeBaseContext
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** The id of the AiKnowledgeBaseContext */
+    contextId: string;
+    /** The number of characters after which text is truncated. Optional */
+    truncateTextAfter?: number;
+}
+/**
+ * Request structure for getting a page of AiKnowledgeBaseContexts
+ * for a given knowledge base
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextsRequest {
+    /** The id of the app */
+    appId: AppId;
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The number of characters after which text is truncated. Optional */
+    truncateTextAfter?: number;
+    /** The number of contexts to skip, for pagination. Optional */
+    offset?: number;
+    /** The maximum number of contexts to return, for pagination. Optional */
+    limit?: number;
+    /** Case-insensitive substring search across id/title only. Optional */
+    search?: string;
+}
+/**
+ * Response structure for getting a page of AiKnowledgeBaseContexts for a given knowledge base
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextsResponse {
+    /** The requested page of AiKnowledgeBaseContexts */
+    contexts: Array<AiKnowledgeBaseContext>;
+    /** The total number of contexts in the AiKnowledgeBase, ignoring offset/limit */
+    totalCount: number;
+}
+/**
+ * Response structure for getting an AiKnowledgeBaseContext
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextResponse {
+    /** The resulting AiKnowledgeBaseContext, if it is found */
+    context: AiKnowledgeBaseContext | undefined;
+}
+/**
+ * Request structure for upserting context for an AiKnowledgeBase
+ * @category AI
+ */
+export interface UpsertAiKnowledgeBaseContextsRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** The AiKnowledgeBaseContext data, which could be a file or text */
+    contextRequests: Array<AiKnowledgeBaseContextRequest>;
+    /** The job ID to use for the async upsert job */
+    jobId: string;
+}
+/**
+ * Response structure for searching an AiKnowledgeBase
+ * @category AI
+ */
+export interface AiKnowledgeBaseSearchResponse {
+    /** Array of result chunks from the search */
+    chunks: Array<AiKnowledgeBaseSearchResultChunk>;
+    /** Traversed subgraph for a `searchMode:'graph'` query with `includeGraphContext`; absent otherwise. */
+    graphContext?: AiKnowledgeBaseGraphContext;
+}
+export type { ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GetKnowledgeBaseGraphStatusRequest, GetKnowledgeBaseGraphStatusResponse, KnowledgeBaseGraphBuildStageUsage, KnowledgeBaseGraphBuildUsage, KnowledgeBaseGraphEdge, KnowledgeBaseGraphFacetStatus, KnowledgeBaseGraphModelUsage, KnowledgeBaseGraphNode, KnowledgeBaseGraphQueryConcepts, KnowledgeBaseGraphQueryDoc, KnowledgeBaseGraphQueryGlobalSummary, KnowledgeBaseGraphQueryMatch, KnowledgeBaseGraphQueryOp, KnowledgeBaseGraphQueryPath, KnowledgeBaseGraphQuerySubtreeNode, KnowledgeBaseGraphRebuildMode, KnowledgeBaseGraphResolutionStatus, KnowledgeBaseGraphTopic, KnowledgeBaseGraphTopicEdge, KnowledgeBaseGraphUsage, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, } from '../public-types/ai-knowledge-base.public-types';
+/**
+ * Request structure for getting the size of context
+ * for an AiKnowledgeBase
+ * @category AI
+ */
+export interface AiKnowledgeBaseContextSizeRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Request structure for the internal test-only route that arms the next `count` grep scans of a
+ * knowledge base to fail at their `maxTimeMS` deadline.
+ */
+export interface AiKnowledgeBaseFailNextGrepScansRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** How many upcoming scans fail; a non-positive value disarms. */
+    count: number;
+}
+/**
+ * Request structure for the internal test-only route that makes one knowledge base's graph be built by
+ * the deterministic stub extractor instead of by the model.
+ */
+export interface AiKnowledgeBaseEnableGraphStubExtractionRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** Gives every entity the stub's pseudo-vector, directive-seeded ones included, so none is embedded. */
+    pseudoVectors?: boolean;
+}
+/**
+ * Request structure for the internal test-only route that shrinks one knowledge base's resolution drain
+ * bounds, so a small corpus needs several rounds or sweeps to drain.
+ */
+export interface AiKnowledgeBaseSetGraphResolutionDrainBoundsRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** Dirty entities one resolution pass examines. */
+    dirtyBatch: number;
+    /** Drain rounds one sweep runs. */
+    maxRounds: number;
+    /** Candidate pairs one drain round adjudicates; the deployment default when absent. */
+    maxPairsPerRound?: number;
+    /** Resolution passes one drain round runs; the deployment default when absent. */
+    maxPasses?: number;
+    /** Adjudication calls kept in flight; the deployment default when absent. */
+    adjudicationConcurrency?: number;
+    /** Dirty entities one pass searches candidates for at once; the deployment default when absent. */
+    proposalConcurrency?: number;
+}
+/**
+ * Request structure for the internal test-only route that drops each entity's own hit from one knowledge
+ * base's resolution ANN results, so a test can make every entity miss itself.
+ */
+export interface AiKnowledgeBaseHideOwnResolutionHitsRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Where a test can park a graph write. `merge-component` holds a resolution merge before it takes the write
+ * lock for its component, `merge` between its snapshot read and its fence, and `merge-fenced` between its
+ * fence and its first write; `entity-read-back` holds a finalize upsert before the read-back that names its
+ * entities, and `entity-provenance` after that read-back's fallback, before its provenance write; `edge-write`
+ * holds it before the edge write, the window its description pass occupies, and `edge-upsert` after the edge
+ * write resolved its endpoints, before it writes. `prune-repair` holds a prune between its bucket delete and
+ * its owner repair.
+ */
+export type GraphWriteGatePoint = 'merge-component' | 'merge' | 'merge-fenced' | 'entity-read-back' | 'entity-provenance' | 'edge-write' | 'edge-upsert' | 'prune-repair';
+/**
+ * Request structure for the internal test-only route that parks one of a knowledge base's graph writes,
+ * so a test can interleave a resolution merge with a bulk-finalize upsert deterministically.
+ */
+export interface AiKnowledgeBaseSetGraphWriteGateRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** Which write to park. */
+    point: GraphWriteGatePoint;
+    /** True parks the next writer at that point; false releases a parked writer and stops parking. */
+    armed: boolean;
+}
+/** Response of the internal test-only graph write-gate route. */
+export interface AiKnowledgeBaseSetGraphWriteGateResponse {
+    /** True once a writer has parked on the gate. */
+    entered: boolean;
+}
+/**
+ * Request structure for the internal test-only route that runs one knowledge base's graph writes without the
+ * per-KB write lock, so a test can pin the interleavings the lock rules out.
+ */
+export interface AiKnowledgeBaseBypassGraphWriteLockRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/** Request structure for the internal test-only route that reports one knowledge base's graph write lock. */
+export interface AiKnowledgeBaseGetGraphWriteLockStateRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/** Response of the internal test-only graph write-lock state route. */
+export interface AiKnowledgeBaseGetGraphWriteLockStateResponse {
+    /** Writers holding the lock shared: finalize entity or edge writes. */
+    sharedHolders: number;
+    /** True while a resolution merge holds the lock exclusive. */
+    exclusiveHeld: boolean;
+    /** Writers queued for a shared hold. */
+    sharedWaiters: number;
+    /** Writers queued for an exclusive hold. */
+    exclusiveWaiters: number;
+}
+/**
+ * Request structure for the internal test-only route that sets a knowledge base's graph schema version.
+ * A migration test needs a KB on the older schema, which the creation path never produces.
+ */
+export interface AiKnowledgeBaseSetGraphSchemaVersionRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The schema version to stamp; omit to clear the stamp so the KB uses the v1 layout. */
+    version?: number;
+}
+/**
+ * Request structure of the operator call that quarantines a knowledge base's dead-weight graph entities
+ * (ENG-2802): entities of degree at most `maxDegree`, cited by at most one chunk, whose name carries no
+ * significant token, is numeric/date-like, or is one token shared by many other entity names.
+ */
+export interface QuarantineKnowledgeBaseGraphEntitiesRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** Reports the matching set without writing anything. */
+    dryRun?: boolean;
+    /** Highest degree a quarantined entity may have: 0 (default) or 1. */
+    maxDegree?: number;
+    /**
+     * How many entities must share a single-token name signature before that token counts as generic;
+     * the deployment default when absent.
+     */
+    frequentSignatureMinEntities?: number;
+}
+/** One entity a quarantine report samples. */
+export interface KnowledgeBaseGraphQuarantineSampleEntity {
+    /** Hex id of the entity document. */
+    id: string;
+    /** Canonical display name. */
+    name: string;
+    /** Extracted entity type. */
+    type: string;
+    /** Relationships touching the entity. */
+    degree: number;
+    /** Chunks citing the entity. */
+    chunkRefCount: number;
+}
+/** Response structure of {@link QuarantineKnowledgeBaseGraphEntitiesRequest}. */
+export interface QuarantineKnowledgeBaseGraphEntitiesResponse {
+    /** Stamped on every entity this run quarantined; absent on a dry run. */
+    runId?: string;
+    /** Entities the criteria match (dry run) or this run quarantined. */
+    matched: number;
+    /** Entities of the partition still live after the run (dry run: before it). */
+    liveEntityCount: number;
+    /** Entities quarantined by this and earlier runs. */
+    quarantinedEntityCount: number;
+    /** Up to 50 matching entities. */
+    sample: KnowledgeBaseGraphQuarantineSampleEntity[];
+}
+/** Request structure of the operator call that restores the entities one quarantine run hid. */
+export interface RestoreKnowledgeBaseGraphEntitiesRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The `runId` the quarantine call returned. */
+    runId: string;
+}
+/** Response structure of {@link RestoreKnowledgeBaseGraphEntitiesRequest}. */
+export interface RestoreKnowledgeBaseGraphEntitiesResponse {
+    /** Entities the call restored. */
+    restored: number;
+    /** Entities still quarantined by other runs. */
+    quarantinedEntityCount: number;
+}
+/**
+ * Request structure for identifying a knowledge base to reimport the context files (when possible).
+ */
+export interface AiKnowledgeBaseReimportAllFilesRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Request structure for identifying a knowledge base to reimport the context files (when possible).
+ */
+export interface AiKnowledgeBaseReimportFilesRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The ids of the AiKnowledgeBaseContexts to reimport */
+    contextIds: Array<string>;
+}
+/** Longest context batch one `backfillFulltext` call accepts; larger work-lists are split by the caller. */
+export declare const BACKFILL_FULLTEXT_MAX_CONTEXTS_PER_CALL = 20;
+/**
+ * Request structure for rebuilding the stored raw text (`kb_fulltext`) of existing contexts from their
+ * stored source files, without re-ingesting them — no chunk, embedding or graph writes. This is how
+ * contexts ingested before literal search existed become greppable.
+ */
+export interface AiKnowledgeBaseBackfillFulltextRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /**
+     * The ids of the contexts to backfill, at most {@link BACKFILL_FULLTEXT_MAX_CONTEXTS_PER_CALL} per
+     * call. Each context's stored text is fully replaced, so re-running a context is safe.
+     */
+    contextIds: Array<AiContextId>;
+    /**
+     * The extraction method for file contexts. Defaults to the server's regular document extraction
+     * default (OCR when configured), which reproduces the text the ingest pipeline indexed — including
+     * scanned pages. `legacy` extracts in-process without any external model call, but yields nothing for
+     * scanned pages, so a caller choosing it must compare the stored part counts against expectations.
+     * `legacy_with_llm` yields the same in-process text here — its page-screenshot descriptions are an
+     * ingest-time addition, not part of the literal text this backfill rebuilds.
+     */
+    extractionMethod?: DocumentExtractionMethod;
+    /**
+     * A context that already has stored text is SKIPPED unless this is true. The backfill rebuilds
+     * literal text only, while ingest also stores image/OCR-description parts — so replacing a context
+     * that ingest populated would silently delete its description text from the literal index. Set this
+     * only to deliberately re-extract contexts this backfill itself populated (e.g. retrying a thin
+     * `legacy` yield with OCR).
+     */
+    overwrite?: boolean;
+}
+/**
+ * Response structure for a `backfillFulltext` call: one status per requested context, in request order.
+ */
+export interface AiKnowledgeBaseBackfillFulltextResponse {
+    statuses: Array<AiKnowledgeBaseBackfillFulltextStatus>;
+}
+/**
+ * Outcome of backfilling the raw text of one context.
+ */
+export interface AiKnowledgeBaseBackfillFulltextStatus {
+    contextId: AiContextId;
+    /** `skipped` means the context already has stored text and `overwrite` was not set; nothing changed. */
+    status: 'success' | 'error' | 'skipped';
+    /**
+     * How many parts (pages/sheets) were stored, on success. Zero means extraction yielded no text at
+     * all — for a `legacy` run over a scanned document that is the expected signal to retry with OCR.
+     */
+    storedPartCount?: number;
+    errorMessage?: string;
+}
+/**
+ * Response structure for getting size of context
+ * @category AI
+ */
+export interface AiKnowledgeBaseContextSizeResponse {
+    /** Size of context bytes, as a number */
+    sizeBytes: number;
+}
+/**
+ * Request structure for getting the values vector of
+ * a specific context
+ *
+ * @category AI
+ */
+export interface AiKnowledgeBaseValueVectorRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The ID of the context */
+    contextId: AiContextId;
+}
+/**
+ * Response structure for getting values vector of a
+ * specific context
+ * @category AI
+ */
+export interface AiKnowledgeBaseValueVectorResponse {
+    /** The vector */
+    vector: number[];
+}
+/**
+ * Internal (console-test-only) extension of the public chat options, for the `test/chat` endpoint
+ * used by the console's KB test-chat panel.
+ * @category AI
+ */
+export interface AiKnowledgeBaseChatOptionsInternal extends AiKnowledgeBaseChatOptions {
+    /**
+     * When true, the response cites sources by name using inline markers — names only, since this
+     * console-test path never mints download links. Takes precedence over the deprecated
+     * `includeReference`. Default to false.
+     */
+    citation?: boolean;
+}
+export interface AiKnowledgeBaseChatRequest {
+    knowledgeBaseId: AiKnowledgeBaseId;
+    prompt?: string;
+    options?: AiKnowledgeBaseChatOptionsInternal;
+}
+/** Emitted to the console queue when a knowledge base or its contexts change. */
+export interface KbChangeEvent {
+    appId: AppId;
+    knowledgeBaseId: AiKnowledgeBaseId;
+    changeType: 'kb' | 'context';
+}

package/dist/internal-common/src/types/ai-matchmaking.types.d.ts

@@ -0,0 +1,19 @@
+import { MmEntity, MmMatchMaker } from '../public-types/ai-matchmaking.public-types';
+/**
+ * Internal-only matchmaking request shapes. Every other request/response of the matchmaking wire
+ * contract is declared in `ai-matchmaking.public-types` and imported directly from there.
+ */
+export interface MmCreateMatchMakerRequest {
+    matchMaker: MmMatchMaker;
+}
+export interface MmGetMatchMakerRequest {
+    matchMakerId: string;
+}
+export interface MmInsertEntityRequest {
+    matchMakerId: string;
+    entity: MmEntity;
+}
+export interface MmGetEntityRequest {
+    matchMakerId: string;
+    entityId: string;
+}

package/dist/internal-common/src/types/backend-function.types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal-common/src/types/communication.types.d.ts

@@ -0,0 +1 @@
+export type ChatId = string;

package/dist/internal-common/src/types/document.types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal-common/src/types/file.types.d.ts

@@ -0,0 +1,6 @@
+export interface Base64File {
+    filename: string;
+    mimetype: string;
+    base64: string;
+    __isSquidBase64File__: true;
+}

package/dist/internal-common/src/types/headers.types.d.ts

@@ -0,0 +1,52 @@
+/** HTTP header names used by Squid for request metadata. */
+export declare const SquidHeaders: {
+    /** Correlates logs and spans across distributed calls. */
+    readonly TRACE_ID: "x-squid-traceid";
+    /** Shared secret header for internal authentication. */
+    readonly SECRET: "x-squid-secret";
+    /** API key provided by the calling application. */
+    readonly APP_API_KEY: "x-app-api-key";
+    /** Unique identifier of the client application. */
+    readonly APP_ID: "x-squid-appid";
+    /** Unique identifier of the end user or service client. */
+    readonly CLIENT_ID: "x-squid-clientid";
+    /**
+     * Marks a request already forwarded between the cores, carrying a digest of the internal API key.
+     *
+     * The receiving core answers such a request itself instead of forwarding it back, and does not
+     * meter it — whichever core took the request from the outside already did. A value derived from a
+     * shared secret is what makes that safe: a caller could otherwise send the header and skip their
+     * own quota. A digest rather than the key itself, because the header reaches tenant code, where
+     * the key would be a privilege escalation; it authorizes nothing, {@link SECRET} is what internal
+     * auth reads.
+     */
+    readonly PROXY_HOP: "x-squid-proxy-hop";
+    /** Version string of the Squid client library. */
+    readonly CLIENT_VERSION: "x-squid-client-version";
+    /** Originating IP address of the request. */
+    readonly SOURCE_IP: "x-squid-source-ip";
+    /**
+     * Response-only: IP of the tenant pod that served the request, i.e. the address to reach it at
+     * again. Core records it to route subsequent affinity-keyed calls to the same pod. Absent when the
+     * pod does not know its own IP.
+     */
+    readonly POD_IP: "x-squid-pod-ip";
+    /**
+     * Response-only: identity of the tenant process that served the request. Distinct from
+     * {@link POD_IP}, which is an address and is reused: Kubernetes hands the IP of a deleted pod to a
+     * new one, so only this value tells core whether it is still talking to the same instance.
+     */
+    readonly INSTANCE_ID: "x-squid-instance-id";
+    /**
+     * Request-only: the {@link INSTANCE_ID} core believes it is calling, sent when routing directly to a
+     * pinned pod instead of through the tenant service. The receiving instance refuses the request when
+     * the value is not its own — the pod at that address may have been replaced, possibly by a pod of a
+     * different application.
+     */
+    readonly EXPECTED_INSTANCE_ID: "x-squid-expected-instance-id";
+    /**
+     * Response-only: key of the tenant worker that served the request, reported separately from
+     * {@link POD_IP} so core alone decides whether to pin at pod or at worker granularity.
+     */
+    readonly WORKER_KEY: "x-squid-worker-key";
+};