@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/member-file-routes.d.ts

@@ -0,0 +1,22 @@
+import type { ChatDeliveryFactory } from "./chat/delivery.js";
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "./authentication.js";
+import type { AfterCommitHook } from "./config.js";
+import type { ConnectionTransportFactory } from "./connections.js";
+import type { ApiPlan } from "./plan.js";
+import type { ReplicationKick } from "./replication.js";
+import { RequestId } from "./errors.js";
+import { OntologyBackend } from "./runtime-contract.js";
+interface MemberFileRoutesOptions {
+    readonly plan: ApiPlan;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
+    readonly chatDelivery?: ChatDeliveryFactory | undefined;
+    readonly verifyToken: TokenVerifier;
+    readonly exchangeSession?: SessionExchange | undefined;
+}
+/** Authenticated users use these routes; the agent's receive/discard routes stay runtime-owned. */
+export declare function memberFileRoutes(options: MemberFileRoutesOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;
+export {};

package/dist/service/member-file-routes.js

@@ -0,0 +1,52 @@
+import { Cause, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { withPrincipal } from "./authentication.js";
+import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
+import { identityToken, makeOperations } from "./operations.js";
+import { memberFileOperations } from "./member-files.js";
+import { OntologyBackend } from "./runtime-contract.js";
+/** Authenticated users use these routes; the agent's receive/discard routes stay runtime-owned. */
+export function memberFileRoutes(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const run = memberFileOperations(backend, options.plan, makeOperations(backend, options.plan, options.hooks, options.connections, options.replicate, options.chatDelivery));
+        const route = (kind) => (request) => Effect.gen(function* () {
+            const bearer = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.bearer).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request));
+            const operation = Effect.gen(function* () {
+                const params = yield* HttpRouter.params;
+                let args = params;
+                if (kind === "attachments-list") {
+                    const query = Object.fromEntries(new URL(request.url, "https://app.invalid").searchParams);
+                    args = {
+                        ...query,
+                        ...(query.limit === undefined ? {} : { limit: Number(query.limit) }),
+                    };
+                }
+                else if (kind === "attachments-promote") {
+                    const body = yield* request.json.pipe(Effect.mapError(() => new InvalidRequestBody({ reason: "invalid_json", issues: [] })));
+                    args =
+                        typeof body === "object" && body !== null && !Array.isArray(body)
+                            ? { ...body, id: params.id }
+                            : body;
+                }
+                const answer = yield* run(kind, args, identityToken(request));
+                return HttpServerResponse.jsonUnsafe(answer, {
+                    headers: { "cache-control": "private, no-store" },
+                });
+            }).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+                ? Effect.failCause(cause)
+                : Effect.flatMap(RequestId, (id) => failureResponse(cause, id))));
+            return yield* withPrincipal(bearer, options.verifyToken, backend, operation, {
+                session: { request, exchange: options.exchangeSession },
+            });
+        });
+        yield* router.add("GET", "/api/ontology/attachments", route("attachments-list"));
+        yield* router.add("GET", "/api/ontology/attachments/:id", route("attachments-get"));
+        yield* router.add("GET", "/api/ontology/attachments/:id/download", route("attachments-download"));
+        yield* router.add("POST", "/api/ontology/attachments/:id/promote", route("attachments-promote"));
+        yield* router.add("GET", "/api/ontology/files/:entity/:id/:property", route("files-download"));
+        yield* router.add("GET", "/api/ontology/files/:entity/:id", route("files-download"));
+    }));
+}

package/dist/service/member-files.d.ts

@@ -0,0 +1,245 @@
+import { Effect, Schema } from "effect";
+import { CurrentPrincipal } from "./authentication.js";
+import { RequestId } from "./errors.js";
+import type { Operations } from "./operations.js";
+import type { ApiPlan } from "./plan.js";
+import type { OntologyBackend } from "./runtime-contract.js";
+export declare const AttachmentFilters: Schema.Struct<{
+    readonly conversation: Schema.optionalKey<Schema.String>;
+    readonly sender_id: Schema.optionalKey<Schema.String>;
+    readonly from: Schema.optionalKey<Schema.String>;
+    readonly to: Schema.optionalKey<Schema.String>;
+    readonly before: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export declare const MEMBER_FILE_SCHEMAS: {
+    "attachments-list": Schema.Struct<{
+        readonly conversation: Schema.optionalKey<Schema.String>;
+        readonly sender_id: Schema.optionalKey<Schema.String>;
+        readonly from: Schema.optionalKey<Schema.String>;
+        readonly to: Schema.optionalKey<Schema.String>;
+        readonly before: Schema.optionalKey<Schema.String>;
+        readonly limit: Schema.optionalKey<Schema.Int>;
+    }>;
+    "attachments-get": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "attachments-download": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "attachments-promote": Schema.Struct<{
+        readonly id: Schema.String;
+        readonly entity: Schema.String;
+        readonly action: Schema.String;
+        readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+        readonly field: Schema.optionalKey<Schema.String>;
+        readonly record_id: Schema.optionalKey<Schema.String>;
+    }>;
+    "files-download": Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly property: Schema.optionalKey<Schema.String>;
+    }>;
+    "files-upload": Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly action: Schema.String;
+        readonly property: Schema.optionalKey<Schema.String>;
+        readonly record_id: Schema.optionalKey<Schema.String>;
+        readonly create_intent: Schema.optionalKey<Schema.String>;
+        readonly idempotency_key: Schema.optionalKey<Schema.String>;
+        readonly filename: Schema.String;
+        readonly content_type: Schema.String;
+        readonly size: Schema.Int;
+    }>;
+    "files-upload-list": Schema.$Record<Schema.String, Schema.Never>;
+    "files-upload-get": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "files-upload-complete": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "files-upload-cancel": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+};
+export type MemberFileOperation = keyof typeof MEMBER_FILE_SCHEMAS;
+export declare function grantForWire(grant: {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    expiresAt: string;
+}): {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    expires_at: string;
+};
+export declare function attachmentForWire(attachment: import("../storage/attachments.js").AttachmentView): {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    sha256: string;
+    state: string;
+    created_at: string;
+    expires_at: string;
+    promotion: unknown;
+    conversation: string | undefined;
+    sender_id: string | undefined;
+};
+/** The member REST and MCP surfaces run the same runtime operations and action pipeline. */
+export declare function memberFileOperations(backend: OntologyBackend["Service"], plan: ApiPlan, operations: Operations): (kind: MemberFileOperation, args: unknown, identityToken?: string) => Effect.Effect<{
+    readonly uploads: readonly {
+        readonly id: string;
+        readonly state: string;
+        readonly filename: string;
+        readonly content_type: string;
+        readonly size: number;
+        readonly entity: string;
+        readonly property: string;
+        readonly action: string;
+        readonly record_id: string | null;
+        readonly create_intent: string | null;
+        readonly created_at: string;
+        readonly expires_at: string;
+        readonly awaiting_action: boolean;
+    }[];
+    readonly pending: number;
+    readonly max: number;
+} | {
+    download: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    };
+    file: {
+        id: string;
+        entity: string;
+        property: string;
+        revision_id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+    };
+    upload?: undefined;
+    attachments?: undefined;
+    nextCursor?: undefined;
+    attachment?: undefined;
+} | {
+    upload: {
+        ticket?: {
+            upload_id: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expires_at: string;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+    attachment?: undefined;
+    download?: undefined;
+} | {
+    options: {
+        create_intent?: string | undefined;
+        idempotency_key: string;
+    };
+    transfer?: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    } | undefined;
+    upload: {
+        ticket?: {
+            upload_id: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expires_at: string;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+    attachment?: undefined;
+    download?: undefined;
+} | {
+    attachments: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    }[];
+    nextCursor: string | null;
+    upload?: undefined;
+    attachment?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    deduplicated: boolean;
+    result: {} | null;
+    upload?: undefined;
+    attachments?: undefined;
+    nextCursor?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    upload?: undefined;
+    attachments?: undefined;
+    nextCursor?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    download: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    };
+    upload?: undefined;
+    attachments?: undefined;
+    nextCursor?: undefined;
+}, unknown, RequestId | CurrentPrincipal>;

package/dist/service/member-files.js

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { MAX_BLOB_BYTES } from "../blob.js";
+import { ActionRejected, NotFound } from "../errors.js";
+import { schemaIssues } from "../runtime/validation.js";
+import { uploadFields } from "../storage/attachments.js";
+import { OpenUploads } from "../storage/sessions.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { InvalidRequestBody, RequestId } from "./errors.js";
+const Id = Schema.String.check(Schema.isUUID());
+const DateTime = Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/));
+export const AttachmentFilters = Schema.Struct({
+    conversation: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200))),
+    sender_id: Schema.optionalKey(Id),
+    from: Schema.optionalKey(DateTime),
+    to: Schema.optionalKey(DateTime),
+    before: Schema.optionalKey(Id),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+const AttachmentId = Schema.Struct({ id: Id });
+const Promotion = Schema.Struct({
+    id: Id,
+    entity: Schema.String,
+    action: Schema.String,
+    input: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+    field: Schema.optionalKey(Schema.String),
+    record_id: Schema.optionalKey(Id),
+});
+const File = Schema.Struct({
+    entity: Schema.String,
+    id: Id,
+    property: Schema.optionalKey(Schema.String),
+});
+/** The REST upload session's begin request; property may be left to the action's upload field. */
+const Upload = Schema.Struct({
+    entity: Schema.String,
+    action: Schema.String,
+    property: Schema.optionalKey(Schema.String),
+    record_id: Schema.optionalKey(Id),
+    create_intent: Schema.optionalKey(Id),
+    idempotency_key: Schema.optionalKey(Id),
+    filename: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(255)),
+    content_type: Schema.String,
+    size: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(MAX_BLOB_BYTES)),
+});
+const UploadId = Schema.Struct({ id: Id });
+export const MEMBER_FILE_SCHEMAS = {
+    "attachments-list": AttachmentFilters,
+    "attachments-get": AttachmentId,
+    "attachments-download": AttachmentId,
+    "attachments-promote": Promotion,
+    "files-download": File,
+    "files-upload": Upload,
+    // Exactly `{}`. MCP lists a tool only with an object input schema, and an empty struct
+    // encodes as "not null".
+    "files-upload-list": Schema.Record(Schema.String, Schema.Never),
+    "files-upload-get": UploadId,
+    "files-upload-complete": UploadId,
+    "files-upload-cancel": UploadId,
+};
+export function grantForWire(grant) {
+    return {
+        url: grant.url,
+        method: grant.method,
+        headers: grant.headers,
+        expires_at: grant.expiresAt,
+    };
+}
+function uploadForWire(upload) {
+    return {
+        id: upload.id,
+        state: upload.state,
+        expires_at: upload.expiresAt,
+        ...(upload.ticket ? { ticket: { upload_id: upload.ticket.uploadId } } : {}),
+    };
+}
+function uploadsForWire(uploads) {
+    return Schema.encodeSync(OpenUploads)(uploads);
+}
+export function attachmentForWire(attachment) {
+    return {
+        id: attachment.id,
+        filename: attachment.filename,
+        content_type: attachment.contentType,
+        size: attachment.size,
+        sha256: attachment.sha256,
+        state: attachment.state,
+        created_at: attachment.createdAt,
+        expires_at: attachment.expiresAt,
+        promotion: attachment.promotion,
+        conversation: attachment.conversation,
+        sender_id: attachment.senderId,
+    };
+}
+function decode(schema, input) {
+    return Schema.decodeUnknownEffect(schema)(input, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error) })));
+}
+/** The member REST and MCP surfaces run the same runtime operations and action pipeline. */
+export function memberFileOperations(backend, plan, operations) {
+    return (kind, args, identityToken) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        if (kind === "files-download") {
+            const input = yield* decode(File, args);
+            if (!backend.blobs) {
+                return yield* new NotFound({
+                    entity: input.entity,
+                    id: input.id,
+                    message: "File storage is unavailable.",
+                });
+            }
+            const result = yield* backend.blobs.downloadFile(input.entity, input.id, input.property ?? "content", {}, principal);
+            return { ...result, download: grantForWire(result.download) };
+        }
+        if (kind === "files-upload" ||
+            kind === "files-upload-list" ||
+            kind === "files-upload-get" ||
+            kind === "files-upload-complete" ||
+            kind === "files-upload-cancel") {
+            if (!backend.blobs) {
+                return yield* new NotFound({
+                    entity: "upload",
+                    id: "",
+                    message: "File storage is unavailable.",
+                });
+            }
+            if (kind === "files-upload-list") {
+                yield* decode(MEMBER_FILE_SCHEMAS[kind], args);
+                if (!backend.blobs.list) {
+                    return yield* new ActionRejected({ message: "file_listing_unavailable" });
+                }
+                return uploadsForWire(yield* backend.blobs.list(principal));
+            }
+            if (kind === "files-upload-get") {
+                const { id } = yield* decode(UploadId, args);
+                return { upload: uploadForWire(yield* backend.blobs.status(id, principal)) };
+            }
+            if (kind === "files-upload-complete") {
+                const { id } = yield* decode(UploadId, args);
+                return { upload: uploadForWire(yield* backend.blobs.complete(id, principal)) };
+            }
+            if (kind === "files-upload-cancel") {
+                const { id } = yield* decode(UploadId, args);
+                return { upload: uploadForWire(yield* backend.blobs.cancel(id, principal)) };
+            }
+            const input = yield* decode(Upload, args);
+            const property = input.property ?? uploadProperty(plan, input.entity, input.action);
+            if (property === undefined) {
+                return yield* new ActionRejected({
+                    message: "Name the property: the action takes no single upload of that entity.",
+                });
+            }
+            // As the app SDK does: the key is the session's identity and the action's idempotency
+            // key, and a record the action creates is bound to the upload by the same create intent.
+            const idempotencyKey = input.idempotency_key ?? randomUUID();
+            const createIntent = input.record_id === undefined ? (input.create_intent ?? idempotencyKey) : undefined;
+            const upload = yield* backend.blobs.begin({
+                entity: input.entity,
+                property,
+                action: input.action,
+                ...(input.record_id === undefined ? {} : { recordId: input.record_id }),
+                ...(createIntent === undefined ? {} : { createIntent }),
+                idempotencyKey,
+                filename: input.filename,
+                contentType: input.content_type,
+                size: input.size,
+            }, principal);
+            // A retry of a transfer already done, or completed, needs no new grant.
+            const transfer = upload.state === "uploading"
+                ? yield* backend.blobs.part(upload.id, principal)
+                : undefined;
+            return {
+                upload: uploadForWire(upload),
+                ...(transfer === undefined ? {} : { transfer: grantForWire(transfer) }),
+                options: {
+                    idempotency_key: idempotencyKey,
+                    ...(createIntent === undefined ? {} : { create_intent: createIntent }),
+                },
+            };
+        }
+        if (principal.kind !== "member") {
+            return yield* new NotFound({
+                entity: "attachment",
+                id: "",
+                message: "Attachment not found.",
+            });
+        }
+        const attachments = backend.attachments;
+        if (!attachments) {
+            return yield* new NotFound({
+                entity: "attachment",
+                id: "",
+                message: "Attachment storage is unavailable.",
+            });
+        }
+        if (kind === "attachments-list") {
+            const input = yield* decode(AttachmentFilters, args);
+            if ((input.from !== undefined && !Number.isFinite(Date.parse(input.from))) ||
+                (input.to !== undefined && !Number.isFinite(Date.parse(input.to))) ||
+                (input.from !== undefined &&
+                    input.to !== undefined &&
+                    Date.parse(input.from) > Date.parse(input.to))) {
+                return yield* new InvalidRequestBody({ reason: "invalid_request", issues: [] });
+            }
+            const { sender_id, ...rest } = input;
+            const result = yield* attachments.listForMember({ ...rest, ...(sender_id === undefined ? {} : { senderId: sender_id }) }, principal);
+            return {
+                attachments: result.attachments.map(attachmentForWire),
+                nextCursor: result.nextCursor,
+            };
+        }
+        if (kind === "attachments-promote") {
+            const input = yield* decode(Promotion, args);
+            const promoted = yield* attachments.promoteForMember(input.id, {
+                entity: input.entity,
+                action: input.action,
+                input: input.input ?? {},
+                ...(input.field === undefined ? {} : { field: input.field }),
+                ...(input.record_id === undefined ? {} : { recordId: input.record_id }),
+            }, principal, (call) => Effect.gen(function* () {
+                const entity = plan.entities.find((item) => item.name === call.entity);
+                const action = entity?.actions.find((item) => item.name === call.action);
+                if (!entity || !action) {
+                    return yield* Effect.die(new Error("The promotion action was not planned."));
+                }
+                const answer = yield* operations.runAction(entity, action, {
+                    input: call.input,
+                    options: call.options,
+                    validateOnly: false,
+                    identityToken,
+                });
+                return { result: answer.result, edits: answer.edits };
+            }).pipe(Effect.provideService(CurrentPrincipal, principal), Effect.provideService(RequestId, requestId)));
+            return { ...promoted, attachment: attachmentForWire(promoted.attachment) };
+        }
+        const { id } = yield* decode(AttachmentId, args);
+        if (kind === "attachments-get") {
+            return { attachment: attachmentForWire(yield* attachments.getForMember(id, principal)) };
+        }
+        const result = yield* attachments.readForMember(id, principal);
+        return {
+            attachment: attachmentForWire(result.attachment),
+            download: grantForWire(result.download),
+        };
+    });
+}
+/** The blob property of the action's only upload field for the entity, if it has exactly one. */
+function uploadProperty(plan, entity, action) {
+    const planned = plan.entities
+        .find((item) => item.name === entity)
+        ?.actions.find((item) => item.name === action);
+    const properties = new Set(planned === undefined
+        ? []
+        : uploadFields(planned.action.input)
+            .filter((field) => field.entity === entity)
+            .map((field) => field.property));
+    return properties.size === 1 ? [...properties][0] : undefined;
+}

package/dist/service/metric-query-platform.d.ts

@@ -0,0 +1,77 @@
+import { Effect, Redacted } from "effect";
+import { MetricQueryUpstreamUnavailable } from "./errors.js";
+/**
+ * How long one metric query may take end to end, the response included. BigQuery answers most within
+ * seconds; the margin covers a cold warehouse and the hops to and from SegmentStream.
+ */
+export declare const METRIC_QUERY_TIMEOUT_MS = 60000;
+/**
+ * The hash of the manifest the service resolved and checked the request against. SegmentStream
+ * answers `409 ontology_version_mismatch` when its deployed manifest differs, so a request checked
+ * against one ontology never runs against another.
+ */
+export declare const MANIFEST_HASH_HEADER = "x-ontology-manifest-hash";
+/**
+ * The entities the service checked `<entity>:read` on, sorted and comma-separated. SegmentStream
+ * answers `409 aggregate_scope_mismatch` when it would read any other, so the service's resolution
+ * and SegmentStream's can never drift apart unnoticed.
+ */
+export declare const TOUCHED_HEADER = "x-ontology-touched";
+/**
+ * The caller's read scopes of the stored entities the request reads scoped, base64url JSON of entity
+ * name to `where`, `me` resolved. SegmentStream keeps only each scope's rows wherever it reads the
+ * entity, confirms the scopes in `execution.rowScopes`, and answers `422
+ * scoped_aggregate_unavailable` for a scope the warehouse cannot apply.
+ */
+export declare const ROW_SCOPES_HEADER = "x-ontology-row-scopes";
+/** SegmentStream would read beyond what the service checked: this deployment's SDK is behind. */
+export declare const SCOPE_MISMATCH = "aggregate_scope_mismatch";
+/** SegmentStream's answer: its status, its JSON body as sent, and that body parsed. */
+export interface PlatformAnswer {
+    readonly status: number;
+    readonly text: string;
+    readonly body: Readonly<Record<string, unknown>>;
+    /** SegmentStream's `Retry-After`, on a 429 or a 503 that sent one. */
+    readonly retryAfter?: string;
+}
+/**
+ * Sends a checked metric query to SegmentStream: model-level, or the per-entity shorthand of `entity`.
+ * `touched` is every entity the service required `<entity>:read` on.
+ */
+export type MetricQueryTransport = (input: {
+    readonly entity?: string;
+    readonly body: unknown;
+    readonly requestId: string;
+    readonly touched: ReadonlyArray<string>;
+    /** {@link ROW_SCOPES_HEADER}'s value, when the caller reads a touched entity scoped. */
+    readonly rowScopes?: string;
+}) => Effect.Effect<PlatformAnswer, MetricQueryUpstreamUnavailable>;
+/**
+ * Where a deployment sends metric queries: its platform, its workspace and its app credential, with the
+ * hash of the manifest it serves.
+ */
+export interface MetricQueryEnvironment {
+    readonly segmentstreamUrl: string;
+    readonly workspaceId: string;
+    readonly appCredential?: Redacted.Redacted<string>;
+    readonly manifestHash: string;
+}
+/** The credential travels only to SegmentStream over TLS, or over plain http to this machine. */
+export declare function securePlatform(origin: string): boolean;
+/**
+ * A failed call for the operator: name, message and stack, then each cause, with every occurrence
+ * of the credential replaced.
+ */
+export declare function describeError(error: unknown, redact: (text: string) => string, depth?: number): string;
+/**
+ * SegmentStream's `POST /api/v1/workspaces/{id}/metrics/query`, and its per-entity
+ * `…/entities/{entity}/metrics/query`, called with the workspace app credential. `undefined` when
+ * the deployment has none, or when SegmentStream's origin is plain http to another machine, which
+ * is logged once. Every request names the manifest it was checked
+ * against, and a redirect is refused, so the credential never leaves for another origin.
+ *
+ * Every answer but a 2xx is logged with both request ids, the status and the start of the body; a
+ * failed call with its message, stack and causes. The credential is redacted from all of them. A
+ * caller who goes away interrupts the call, which is not SegmentStream's failure.
+ */
+export declare function platformMetricQueries(environment: MetricQueryEnvironment, fetchImpl?: typeof fetch): MetricQueryTransport | undefined;