@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/caller-context.d.ts

@@ -0,0 +1,24 @@
+import { Context, Effect } from "effect";
+/** Verified credential provenance, never the bearer value or a client-supplied sender. */
+export type VerifiedCaller = {
+    readonly kind: "oauth";
+    readonly subjectId: string;
+    readonly client: {
+        readonly id: string;
+        readonly name: string;
+    };
+    readonly scope: string;
+} | {
+    readonly kind: "runtime" | "service" | "member" | "workload";
+    readonly subjectId: string;
+};
+export type CallerContext = VerifiedCaller | {
+    readonly kind: "unverified";
+};
+declare const CurrentCaller_base: Context.ServiceClass<CurrentCaller, "@segmentstream/ontology/CurrentCaller", VerifiedCaller>;
+/** Provided only after authentication, alongside the independently scoped principal. */
+export declare class CurrentCaller extends CurrentCaller_base {
+}
+/** Direct in-process operation callers have no credential provenance and cannot acquire attribution. */
+export declare const currentCaller: Effect.Effect<CallerContext, never, never>;
+export {};

package/dist/service/caller-context.js

@@ -0,0 +1,6 @@
+import { Context, Effect, Option } from "effect";
+/** Provided only after authentication, alongside the independently scoped principal. */
+export class CurrentCaller extends Context.Service()("@segmentstream/ontology/CurrentCaller") {
+}
+/** Direct in-process operation callers have no credential provenance and cannot acquire attribution. */
+export const currentCaller = Effect.serviceOption(CurrentCaller).pipe(Effect.map((caller) => Option.getOrElse(caller, () => ({ kind: "unverified" }))));

package/dist/service/catalog.d.ts

@@ -0,0 +1,42 @@
+import { type OntologyManifest } from "../manifest.js";
+/**
+ * The catalog for a reader: the manifest, with each entity's actions narrowed to the ones the given
+ * permissions may run, and only the metrics of the model whose every input entity they may read.
+ * Without permissions it is the manifest itself.
+ */
+export declare function catalogFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): OntologyManifest;
+export interface GraphRelationship {
+    readonly from: string;
+    readonly name: string;
+    readonly to: string;
+    readonly inverse: string;
+    readonly cardinality: "one" | "many";
+    /** The property pair of a relationship matched by value: one with a warehouse-backed end. */
+    readonly on?: {
+        readonly property: string;
+        readonly targetProperty: string;
+    };
+    /**
+     * Whether the relationship may lead to nothing. Only a stored → stored `rel.one` can promise a
+     * record; a value-matched reference is never checked against its target.
+     */
+    readonly optional: boolean;
+    readonly phrase: readonly [string, string];
+    /** The relationship read from the declaring entity: "Lead is owned by one User". */
+    readonly forward: string;
+    /** The relationship read from the target: "User owns many Leads". */
+    readonly backward: string;
+    readonly description: string;
+}
+export interface Graph {
+    readonly hash: string;
+    readonly entities: ReadonlyArray<{
+        readonly name: string;
+        readonly label: string;
+        readonly plural: string;
+        readonly description: string;
+    }>;
+    readonly relationships: ReadonlyArray<GraphRelationship>;
+}
+/** The entities and both directions of every relationship, phrased. */
+export declare function graphOf(manifest: OntologyManifest): Graph;

package/dist/service/catalog.js

@@ -0,0 +1,66 @@
+import { isValueMatched } from "../manifest.js";
+import { isAllowed } from "../permissions.js";
+import { actionPermission, modelMetricsFor } from "../render.js";
+/**
+ * The catalog for a reader: the manifest, with each entity's actions narrowed to the ones the given
+ * permissions may run, and only the metrics of the model whose every input entity they may read.
+ * Without permissions it is the manifest itself.
+ */
+export function catalogFor(manifest, permissions) {
+    if (permissions === undefined) {
+        return manifest;
+    }
+    const { metrics: declared, ...rest } = manifest;
+    const metrics = declared === undefined ? [] : modelMetricsFor(manifest, permissions);
+    return {
+        ...rest,
+        ...(metrics.length === 0 ? {} : { metrics }),
+        entities: manifest.entities
+            .filter((entity) => entity.source === undefined ||
+            isAllowed(entity.permissions?.read ?? `${entity.name}:read`, { permissions }))
+            .map((entity) => ({
+            ...entity,
+            actions: entity.actions.filter((action) => isAllowed(actionPermission(entity.name, action), { permissions })),
+        })),
+    };
+}
+/** The entities and both directions of every relationship, phrased. */
+export function graphOf(manifest) {
+    const entities = new Map(manifest.entities.map((entity) => [entity.name, entity]));
+    return {
+        hash: manifest.hash,
+        entities: manifest.entities.map(({ name, label, plural, description }) => ({
+            name,
+            label,
+            plural,
+            description,
+        })),
+        relationships: manifest.entities.flatMap((source) => source.relationships.map((relationship) => {
+            const target = entities.get(relationship.to);
+            const targetLabel = target?.label ?? relationship.to;
+            // Manifests before version 5 wrote `optional` on warehouse → stored relationships too.
+            const valueMatched = isValueMatched(relationship) ||
+                source.source !== undefined ||
+                target?.source !== undefined;
+            // As describe phrases them: nothing promises a value-matched relationship a record.
+            const one = valueMatched ? "at most one" : "one";
+            const many = valueMatched ? "" : "many ";
+            const forwardTarget = relationship.cardinality === "one"
+                ? `${one} ${targetLabel}`
+                : `many ${target?.plural ?? relationship.to}`;
+            return {
+                from: source.name,
+                name: relationship.name,
+                to: relationship.to,
+                inverse: relationship.inverse,
+                cardinality: relationship.cardinality,
+                ...(relationship.on !== undefined ? { on: relationship.on } : {}),
+                optional: relationship.cardinality === "many" || valueMatched || relationship.optional === true,
+                phrase: relationship.phrase,
+                forward: `${source.label} ${relationship.phrase[0]} ${forwardTarget}`,
+                backward: `${targetLabel} ${relationship.phrase[1]} ${many}${source.plural}`,
+                description: relationship.description,
+            };
+        })),
+    };
+}

package/dist/service/channel/provider.d.ts

@@ -0,0 +1,10 @@
+import type { Effect } from "effect";
+import type { ConnectionTransport } from "../../connection.js";
+import type { ChannelSignInInput } from "../runtime-contract.js";
+/** Verified provider facts only; admission and session issuance remain provider-independent. */
+export interface ChannelAppProvider {
+    readonly provider: string;
+    readonly verify: (assertion: string, ctx: {
+        readonly connections: ConnectionTransport["Service"];
+    }) => Effect.Effect<Omit<ChannelSignInInput, "provider"> | undefined>;
+}

package/dist/service/channel/provider.js

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

package/dist/service/channel/providers/telegram.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import type { ConnectionTransport } from "../../../connection.js";
+import type { ChannelAppProvider } from "../provider.js";
+import type { ChannelSignInInput } from "../../runtime-contract.js";
+export declare const TELEGRAM_PRODUCTION_PUBLIC_KEY = "e7bf03a2fa4602af4580703d88dda5bb59f32ed8b02a56c187fe7d34caed242d";
+export declare const INIT_DATA_MAX_AGE_SECONDS = 3600;
+export declare const INIT_DATA_FUTURE_SKEW_SECONDS = 30;
+/** No bot secret, browser bot ID, or unverified initDataUnsafe participates in this assertion. */
+export declare function verifyTelegramInitData(input: {
+    readonly initData: string;
+    readonly botId: string;
+    readonly testPublicKeyHex?: string;
+    readonly now?: number;
+}): ChannelSignInInput | undefined;
+/** Bot IDs come only from the workspace's configured Telegram connection, cached for five minutes. */
+export declare function telegramBotId(connection: string): (transport: ConnectionTransport["Service"]) => Effect.Effect<string, never, never>;
+/** Only an explicit deployment option registers this adapter; a chat connection alone does not. */
+export declare function telegramAppProvider(connection: string, testPublicKeyHex?: string): ChannelAppProvider;

package/dist/service/channel/providers/telegram.js

@@ -0,0 +1,108 @@
+import { createPublicKey, verify } from "node:crypto";
+import { Effect } from "effect";
+// Verified against https://core.telegram.org/bots/webapps#validating-data-for-third-party-use
+export const TELEGRAM_PRODUCTION_PUBLIC_KEY = "e7bf03a2fa4602af4580703d88dda5bb59f32ed8b02a56c187fe7d34caed242d";
+export const INIT_DATA_MAX_AGE_SECONDS = 3600;
+export const INIT_DATA_FUTURE_SKEW_SECONDS = 30;
+/** No bot secret, browser bot ID, or unverified initDataUnsafe participates in this assertion. */
+export function verifyTelegramInitData(input) {
+    try {
+        if (input.initData.length === 0 || input.initData.length > 16_384) {
+            return undefined;
+        }
+        const params = new URLSearchParams(input.initData);
+        const fields = new Map();
+        for (const [key, value] of params) {
+            if (fields.has(key)) {
+                return undefined;
+            }
+            fields.set(key, value);
+        }
+        const signature = fields.get("signature") ?? "";
+        const authDate = fields.get("auth_date") ?? "";
+        const nowSeconds = (input.now ?? Date.now()) / 1000;
+        const age = nowSeconds - Number(authDate);
+        if (!/^[A-Za-z0-9_-]{86}(?:==)?$/.test(signature) ||
+            !/^[0-9]+$/.test(authDate) ||
+            !Number.isSafeInteger(Number(authDate)) ||
+            age > INIT_DATA_MAX_AGE_SECONDS ||
+            age < -INIT_DATA_FUTURE_SKEW_SECONDS) {
+            return undefined;
+        }
+        const lines = [...fields]
+            .filter(([key]) => key !== "hash" && key !== "signature")
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, value]) => `${key}=${value}`);
+        const publicKey = createPublicKey({
+            key: Buffer.concat([
+                Buffer.from("302a300506032b6570032100", "hex"),
+                Buffer.from(input.testPublicKeyHex ?? TELEGRAM_PRODUCTION_PUBLIC_KEY, "hex"),
+            ]),
+            format: "der",
+            type: "spki",
+        });
+        if (!verify(null, Buffer.from(`${input.botId}:WebAppData\n${lines.join("\n")}`), publicKey, Buffer.from(signature, "base64url"))) {
+            return undefined;
+        }
+        const user = JSON.parse(fields.get("user") ?? "null");
+        if (!user || !Number.isSafeInteger(user.id) || Number(user.id) <= 0 || user.is_bot === true) {
+            return undefined;
+        }
+        const display = [user.first_name, user.last_name]
+            .filter((value) => typeof value === "string")
+            .join(" ")
+            .trim();
+        return {
+            provider: "telegram",
+            externalId: String(user.id),
+            ...(display ? { display } : {}),
+            ...(typeof user.username === "string" ? { username: user.username } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Bot IDs come only from the workspace's configured Telegram connection, cached for five minutes. */
+export function telegramBotId(connection) {
+    let cached;
+    return (transport) => Effect.gen(function* () {
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.id;
+        }
+        const response = yield* transport.request({
+            connection,
+            api: "bot",
+            method: "GET",
+            path: "/getMe",
+            headers: [],
+            body: new Uint8Array(),
+        });
+        const body = yield* Effect.try(() => JSON.parse(new TextDecoder().decode(response.body)));
+        if (response.status !== 200 ||
+            body.ok !== true ||
+            body.result?.is_bot !== true ||
+            !Number.isSafeInteger(body.result.id) ||
+            Number(body.result.id) <= 0) {
+            const explanation = typeof body.description === "string"
+                ? body.description
+                : `Unexpected getMe response (HTTP ${response.status}).`;
+            return yield* Effect.die(new Error("Telegram getMe did not return a bot identity.", {
+                cause: new Error(explanation),
+            }));
+        }
+        cached = { id: String(body.result.id), expiresAt: Date.now() + 300_000 };
+        return cached.id;
+    }).pipe(Effect.orDie);
+}
+/** Only an explicit deployment option registers this adapter; a chat connection alone does not. */
+export function telegramAppProvider(connection, testPublicKeyHex) {
+    const botId = telegramBotId(connection);
+    return {
+        provider: "telegram",
+        verify: (assertion, ctx) => Effect.gen(function* () {
+            const id = yield* botId(ctx.connections);
+            return verifyTelegramInitData({ initData: assertion, botId: id, testPublicKeyHex });
+        }),
+    };
+}

package/dist/service/channel/sessions.d.ts

@@ -0,0 +1,5 @@
+export { channelCookieName } from "../../channel-session.js";
+import type { OntologyServiceConfig } from "../config.js";
+import { OntologyBackend } from "../runtime-contract.js";
+/** Discovery and logout for workspace-owned channel sessions, outside the Neon catch-all. */
+export declare function channelSessionLayer(config: OntologyServiceConfig): import("effect/Layer").Layer<never, never, OntologyBackend | import("effect/unstable/http/HttpRouter").HttpRouter>;

package/dist/service/channel/sessions.js

@@ -0,0 +1,53 @@
+import { CHANNEL_LOGOUT_PATH, CHANNEL_SESSION_PATH, channelCookie, channelCookieName, } from "../../channel-session.js";
+export { channelCookieName } from "../../channel-session.js";
+import { Effect } from "effect";
+import { HttpServerResponse } from "effect/unstable/http";
+import { use as registerRoutes } from "effect/unstable/http/HttpRouter";
+import { sessionMayAuthenticate } from "../authentication.js";
+import { appSessionResource, publicOrigin, secretHash, sameResource, callerOfAccessToken, } from "../oauth/protocol.js";
+import { OntologyBackend } from "../runtime-contract.js";
+const json = (body, status = 200, headers = {}) => HttpServerResponse.jsonUnsafe(body, {
+    status,
+    headers: { "cache-control": "no-store", ...headers },
+});
+/** Discovery and logout for workspace-owned channel sessions, outside the Neon catch-all. */
+export function channelSessionLayer(config) {
+    const cookieName = channelCookieName(config.workspaceId);
+    return registerRoutes((router) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        yield* router.add("GET", CHANNEL_SESSION_PATH, (request) => Effect.gen(function* () {
+            const token = request.cookies[cookieName];
+            if (!token || !backend.oauth) {
+                return json({ error: "unauthorized" }, 401);
+            }
+            const resource = appSessionResource(publicOrigin(request));
+            const caller = yield* callerOfAccessToken(backend.oauth, token, resource);
+            const grant = caller ? yield* backend.oauth.findAccess(secretHash(token)) : undefined;
+            return caller && grant
+                ? json({
+                    session: { id: grant.id, expires_at: grant.expiresAt?.toISOString() },
+                    user: { id: caller.principal.id },
+                })
+                : json({ error: "unauthorized" }, 401);
+        }));
+        yield* router.add("POST", CHANNEL_LOGOUT_PATH, (request) => Effect.gen(function* () {
+            if (!sessionMayAuthenticate(request)) {
+                return json({ error: "cross_origin_session" }, 403);
+            }
+            // Server sign-out can forward the opaque cookie as bearer, with the same Origin check.
+            const authorization = request.headers.authorization;
+            const token = authorization?.startsWith("Bearer ")
+                ? authorization.slice(7)
+                : request.cookies[cookieName];
+            if (token && backend.oauth) {
+                const grant = yield* backend.oauth.findGrantOfToken(secretHash(token));
+                if (grant && sameResource(grant.resource, appSessionResource(publicOrigin(request)))) {
+                    yield* backend.oauth.revokeGrant(grant.id);
+                }
+            }
+            return json({ signed_out: true }, 200, {
+                "set-cookie": channelCookie(cookieName, "", 0),
+            });
+        }));
+    }));
+}

package/dist/service/channel/sign-in.d.ts

@@ -0,0 +1,7 @@
+import type { ChannelAppProvider } from "./provider.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import type { OntologyServiceConfig } from "../config.js";
+import { RequestId } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+/** Public assertion exchange: only an explicitly registered adapter reaches shared admission. */
+export declare function channelSignInLayer(providers: readonly ChannelAppProvider[], config: OntologyServiceConfig, connections: ConnectionTransportFactory): import("effect/Layer").Layer<never, never, OntologyBackend | import("effect/unstable/http/HttpRouter").HttpRouter | import("effect/unstable/http/HttpRouter").Request<"Requires", RequestId> | import("effect/unstable/http/HttpRouter").Request<"Error", import("effect/unstable/http/HttpServerError").HttpServerError>>;

package/dist/service/channel/sign-in.js

@@ -0,0 +1,78 @@
+import { Effect } from "effect";
+import { HttpServerResponse } from "effect/unstable/http";
+import { params, use as registerRoutes } from "effect/unstable/http/HttpRouter";
+import { CHANNEL_SESSION_TTL_SECONDS, channelCookie, channelCookieName, } from "../../channel-session.js";
+import { sessionMayAuthenticate } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { appSessionResource, publicOrigin } from "../oauth/protocol.js";
+import { clientAddress, fixedWindowLimiter } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+const json = (body, status = 200, headers = {}) => HttpServerResponse.jsonUnsafe(body, {
+    status,
+    headers: { "cache-control": "no-store", ...headers },
+});
+/** Public assertion exchange: only an explicitly registered adapter reaches shared admission. */
+export function channelSignInLayer(providers, config, connections) {
+    const limiter = fixedWindowLimiter({ limit: 10, windowMs: 60_000, maxKeys: 10_000 });
+    const cookieName = channelCookieName(config.workspaceId);
+    return registerRoutes((router) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        yield* router.add("POST", "/api/ontology/sign-in/:provider", (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            if (!sessionMayAuthenticate(request)) {
+                return json({ error: "cross_origin_session" }, 403);
+            }
+            const retryAfter = limiter.take(clientAddress(request));
+            if (retryAfter !== undefined) {
+                return json({ error: "rate_limited" }, 429, { "retry-after": String(retryAfter) });
+            }
+            const route = yield* params;
+            const provider = providers.find((candidate) => route.provider === candidate.provider);
+            if (!provider) {
+                return json({ error: "not_found" }, 404);
+            }
+            if (!backend.channelSessions) {
+                return json({ error: "channel_unavailable" }, 503);
+            }
+            const text = yield* request.text;
+            let assertion;
+            try {
+                assertion =
+                    text.length <= 32_768
+                        ? JSON.parse(text)?.assertion
+                        : undefined;
+            }
+            catch {
+                return json({ error: "invalid_request" }, 400);
+            }
+            if (typeof assertion !== "string" || assertion.length > 16_384) {
+                return json({ error: "invalid_request" }, 400);
+            }
+            const identity = yield* provider.verify(assertion, {
+                connections: connections({
+                    identityToken: request.headers["x-vercel-oidc-token"],
+                    audit: { action: "channel.sign_in", principalId: "anonymous", requestId },
+                }),
+            });
+            if (!identity) {
+                return json({ error: "invalid_assertion" }, 401);
+            }
+            const session = yield* backend.channelSessions.create({
+                ...identity,
+                provider: provider.provider,
+                resource: appSessionResource(publicOrigin(request)),
+            });
+            if (session.status === "limited") {
+                return json({ error: "rate_limited" }, 429, {
+                    "retry-after": String(session.retryAfterSeconds),
+                });
+            }
+            if (session.status !== "signed_in") {
+                return json({ error: session.status === "pairing_required" ? "not_paired" : "access_refused" }, 403);
+            }
+            return json({ signed_in: true, expires_at: session.expiresAt.toISOString() }, 200, {
+                "set-cookie": channelCookie(cookieName, session.token, CHANNEL_SESSION_TTL_SECONDS),
+            });
+        }));
+    }));
+}

package/dist/service/chat/archive.d.ts

@@ -0,0 +1,64 @@
+import { Effect, Schema } from "effect";
+import type { OntologyEnvironment } from "../config.js";
+import type { ConversationRequester } from "./attribution.js";
+export interface DeliveryEvent {
+    readonly eventId: string;
+    readonly operationId: string;
+    readonly provider: string;
+    readonly chatId: string;
+    readonly chatType: "group" | "private";
+    readonly threadId: null;
+    readonly participantIds: ReadonlyArray<string>;
+    readonly senderId: string;
+    readonly senderName: string;
+    readonly senderIsBot: true;
+    readonly kind: "outbound";
+    readonly messageId: string | null;
+    readonly replyToMessageId: string | null;
+    readonly sessionId: string | null;
+    readonly turnId: null;
+    readonly text: string;
+    readonly decision: null;
+    readonly reason: null;
+    readonly toolCallId: null;
+    readonly toolName: null;
+    readonly argsSummary: string | null;
+    readonly status: "requested" | "sent" | "uncertain" | "failed";
+    readonly attachments: readonly [];
+    readonly requestedBy: ConversationRequester;
+    readonly url: string | null;
+    readonly at: string;
+}
+export interface DeliveryCommand {
+    readonly phase: "reserve" | "receipt";
+    readonly scope: string;
+    readonly key: string;
+    readonly fingerprint: string;
+    readonly claimId?: string;
+}
+export declare const DeliveryReceipt: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly claimed: Schema.Boolean;
+    readonly duplicate: Schema.Boolean;
+    readonly operationId: Schema.String;
+    readonly claimId: Schema.optionalKey<Schema.String>;
+    readonly status: Schema.Literals<readonly ["sent", "uncertain", "failed"]>;
+    readonly messageId: Schema.NullOr<Schema.String>;
+    readonly url: Schema.NullOr<Schema.String>;
+    readonly historyRecorded: Schema.Boolean;
+}>;
+export type DeliveryReceipt = typeof DeliveryReceipt.Type;
+declare const DeliveryArchiveError_base: Schema.Class<DeliveryArchiveError, Schema.TaggedStruct<"DeliveryArchiveError", {
+    readonly diagnostic: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+export declare class DeliveryArchiveError extends DeliveryArchiveError_base {
+}
+export type DeliveryArchive = (input: {
+    readonly event: DeliveryEvent;
+    readonly delivery: DeliveryCommand;
+    readonly identityToken: string | undefined;
+}) => Effect.Effect<DeliveryReceipt, DeliveryArchiveError>;
+/** One append attempt only. A response without the v1 claim protocol cannot authorize a send. */
+export declare function platformDeliveryArchive(environment: OntologyEnvironment, fetchImpl?: typeof fetch): DeliveryArchive;
+export {};

package/dist/service/chat/archive.js

@@ -0,0 +1,62 @@
+import { Effect, Schema } from "effect";
+export const DeliveryReceipt = Schema.Struct({
+    version: Schema.Literal(1),
+    claimed: Schema.Boolean,
+    duplicate: Schema.Boolean,
+    operationId: Schema.String,
+    claimId: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+    status: Schema.Literals(["sent", "uncertain", "failed"]),
+    messageId: Schema.NullOr(Schema.String),
+    url: Schema.NullOr(Schema.String),
+    historyRecorded: Schema.Boolean,
+});
+export class DeliveryArchiveError extends Schema.TaggedError()("DeliveryArchiveError", {
+    diagnostic: Schema.String,
+    cause: Schema.optionalKey(Schema.Unknown),
+}) {
+}
+/** One append attempt only. A response without the v1 claim protocol cannot authorize a send. */
+export function platformDeliveryArchive(environment, fetchImpl = fetch) {
+    return ({ event, delivery, identityToken }) => Effect.tryPromise({
+        try: async (signal) => {
+            if (!identityToken) {
+                throw new Error("The archive requires a production runtime identity.");
+            }
+            const origin = new URL(environment.segmentstreamUrl);
+            if (origin.username ||
+                origin.password ||
+                origin.search ||
+                origin.hash ||
+                (origin.protocol !== "https:" &&
+                    !(origin.protocol === "http:" &&
+                        ["127.0.0.1", "localhost", "[::1]"].includes(origin.hostname)))) {
+                throw new Error("The archive endpoint must use HTTPS or local loopback HTTP.");
+            }
+            const base = `${environment.segmentstreamUrl}/api/internal/v1/workspaces/` +
+                encodeURIComponent(environment.workspaceId);
+            const response = await fetchImpl(`${base}/agent/conversations/events`, {
+                method: "POST",
+                redirect: "error",
+                headers: {
+                    "content-type": "application/json",
+                    "x-segmentstream-organization-id": environment.organizationId,
+                    "x-segmentstream-runtime-identity": identityToken,
+                },
+                body: JSON.stringify({ ...event, delivery }),
+                signal: AbortSignal.any([signal, AbortSignal.timeout(15_000)]),
+            });
+            if (!response.ok) {
+                throw new DeliveryArchiveError({
+                    diagnostic: response.status === 409 ? "chat_archive_conflict" : "chat_archive_append_failed",
+                    cause: new Error(`Archive HTTP ${response.status}; ` +
+                        `request ${response.headers.get("x-request-id") ?? "unknown"}.`),
+                });
+            }
+            const result = Schema.decodeUnknownSync(Schema.Struct({ stored: Schema.Literal(true), delivery: DeliveryReceipt }))(await response.json());
+            return result.delivery;
+        },
+        catch: (cause) => cause instanceof DeliveryArchiveError
+            ? cause
+            : new DeliveryArchiveError({ diagnostic: "chat_archive_append_failed", cause }),
+    });
+}

package/dist/service/chat/attribution.d.ts

@@ -0,0 +1,26 @@
+import type { ChatAttributionSettings } from "../../chat.js";
+import { Effect } from "effect";
+import { PermissionDenied } from "../../errors.js";
+import type { Principal } from "../../runtime.js";
+import type { CallerContext } from "../caller-context.js";
+/** Display metadata identifies the registered client; it does not certify ownership of its name. */
+export declare function chatAttribution(caller: CallerContext, name: string, settings?: ChatAttributionSettings): string | null;
+/** The archive snapshot for posting, built exclusively from authenticated identity and stored names. */
+export declare function deliveryRequester(caller: CallerContext, principal: Principal, name: string, settings?: ChatAttributionSettings): Effect.Effect<never, PermissionDenied, never> | Effect.Effect<{
+    id: string;
+    kind: "member" | "service";
+    name: string;
+    via: "oauth" | "service" | "hq";
+    clientId: string | null;
+    clientName: string | null;
+    attribution: string;
+}, never, never>;
+export interface ConversationRequester {
+    readonly id: string;
+    readonly kind: "member" | "service";
+    readonly name: string;
+    readonly via: "oauth" | "hq" | "service";
+    readonly clientId: string | null;
+    readonly clientName: string | null;
+    readonly attribution: string;
+}

package/dist/service/chat/attribution.js

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+import { PermissionDenied } from "../../errors.js";
+/** Display metadata identifies the registered client; it does not certify ownership of its name. */
+export function chatAttribution(caller, name, settings = {}) {
+    if (caller.kind !== "oauth" && caller.kind !== "runtime" && caller.kind !== "service") {
+        return null;
+    }
+    return (settings.template ?? "{name}").replace(/\{(name|client)\}/g, (_, key) => key === "name" ? name : caller.kind === "oauth" ? caller.client.name : "");
+}
+/** The archive snapshot for posting, built exclusively from authenticated identity and stored names. */
+export function deliveryRequester(caller, principal, name, settings = {}) {
+    const attribution = chatAttribution(caller, name, settings);
+    if ((caller.kind !== "oauth" && caller.kind !== "runtime" && caller.kind !== "service") ||
+        caller.subjectId !== principal.id ||
+        attribution === null ||
+        principal.kind !== (caller.kind === "service" ? "service" : "member")) {
+        return Effect.fail(new PermissionDenied({ message: "This credential cannot attribute a chat post." }));
+    }
+    return Effect.succeed({
+        id: principal.id,
+        kind: principal.kind,
+        name,
+        via: caller.kind === "runtime" ? "hq" : caller.kind,
+        clientId: caller.kind === "oauth" ? caller.client.id : null,
+        clientName: caller.kind === "oauth" ? caller.client.name : null,
+        attribution,
+    });
+}

package/dist/service/chat/delivery.d.ts

@@ -0,0 +1,18 @@
+import { type TelegramPreviewContext } from "../../telegram.js";
+import { ChatDelivery } from "../../chat.js";
+import type { Ontology } from "../../ontology.js";
+import type { Principal } from "../../runtime.js";
+import type { CallerContext } from "../caller-context.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import type { OntologyBackend } from "../runtime-contract.js";
+import type { DeliveryArchive } from "./archive.js";
+import type { RuntimeChatEnvelope } from "./envelope.js";
+export type ChatDeliveryFactory = (input: {
+    readonly backend: OntologyBackend["Service"];
+    readonly principal: Principal;
+    readonly caller: CallerContext;
+    readonly identityToken: string | undefined;
+    readonly requestId: string;
+    readonly envelope?: RuntimeChatEnvelope;
+}) => ChatDelivery["Service"];
+export declare function makeChatDelivery(ontology: Ontology, connections: ConnectionTransportFactory, archive: DeliveryArchive, previews?: TelegramPreviewContext): ChatDeliveryFactory;