@zackbart/connecta 0.28.1 → 0.29.0

package/dist/access-tokens.js

@@ -1,35 +1,27 @@
+import { authorizationCredential, isMachineCredential } from "./inbound-credential.js";
+import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeAccessTokens } from "./routes/access-tokens.js";
 import { validIdentityReference } from "./identity.js";
+import { accessTokenKeys } from "./storage/keys.js";
 const TOKEN_PREFIX = "cta_";
 const TOKEN_BYTES = 32;
 const TOKEN_VALUE_RE = /^cta_[A-Za-z0-9_-]{43}$/;
-const RECORD_PREFIX = "access-token:v1:record:";
-const LOOKUP_PREFIX = "access-token:v1:lookup:";
 const MAX_NAME_CHARACTERS = 80;
 const DEFAULT_MAX_ACTIVE = 100;
 const MAX_CONFIGURED_ACTIVE = 1_000;
-const ACTIVE_KEY = "access-token:v1:active";
 const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
 const encoder = new TextEncoder();
-function recordKey(id) {
-    return `${RECORD_PREFIX}${id}`;
-}
-function lookupKey(hash) {
-    return `${LOOKUP_PREFIX}${hash}`;
-}
+const recordKey = accessTokenKeys.record;
+const lookupKey = accessTokenKeys.lookup;
+const ACTIVE_KEY = accessTokenKeys.active;
 function bytesToBase64Url(bytes) {
     let binary = "";
     for (const byte of bytes)
         binary += String.fromCharCode(byte);
-    return btoa(binary)
-        .replaceAll("+", "-")
-        .replaceAll("/", "_")
-        .replace(/=+$/u, "");
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
 }
 function bytesToHex(bytes) {
-    return [...bytes]
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 async function hashToken(token) {
     return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))));
@@ -62,12 +54,10 @@ function parseRecord(raw) {
             typeof value.createdAt !== "string" ||
             !Number.isFinite(Date.parse(value.createdAt)) ||
             typeof value.createdBy !== "string" ||
-            (value.principal !== undefined &&
-                !validIdentityReference(value.principal)) ||
+            (value.principal !== undefined && !validIdentityReference(value.principal)) ||
             (value.revokedAt !== undefined &&
                 (typeof value.revokedAt !== "string" || !value.revokedAt || !Number.isFinite(Date.parse(value.revokedAt)))) ||
-            (value.revokedBy !== undefined &&
-                typeof value.revokedBy !== "string")) {
+            (value.revokedBy !== undefined && typeof value.revokedBy !== "string")) {
             throw new Error("invalid token record");
         }
         return value;
@@ -119,18 +109,20 @@ export class AccessTokenManager {
     maxActive;
     constructor(storage, options = {}) {
         this.storage = storage;
-        if (!storage.list) {
-            throw new Error("accessTokens requires a storage adapter that implements list(prefix)");
+        // Issuance claims capacity by compare-and-set and listing enumerates
+        // records; refuse a store without either here, not at the first create.
+        if (typeof storage?.list !== "function" || typeof storage.compareAndSet !== "function") {
+            throw new Error("accessTokens requires storage that implements list and compareAndSet " +
+                "(d1Storage, sqliteStorage, or memoryStorage)");
         }
         const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
-        if (!Number.isInteger(maxActive) ||
-            maxActive < 1 ||
-            maxActive > MAX_CONFIGURED_ACTIVE) {
+        if (!Number.isInteger(maxActive) || maxActive < 1 || maxActive > MAX_CONFIGURED_ACTIVE) {
             throw new Error(`accessTokens.maxActive must be a whole number from 1 to ${MAX_CONFIGURED_ACTIVE}`);
         }
         this.maxActive = maxActive;
         this.auth = {
             kind: "access_token",
+            recognizesCredential: isMachineCredential,
             activityActorNamespace: "connecta:access-tokens:v1",
             activityActorLabel: async (id) => {
                 try {
@@ -153,7 +145,7 @@ export class AccessTokenManager {
         return record;
     }
     async list() {
-        const keys = await this.storage.list(RECORD_PREFIX);
+        const keys = await this.storage.list(accessTokenKeys.recordPrefix);
         const records = await Promise.all(keys.map(async (key) => {
             const raw = await this.storage.get(key);
             return raw ? parseRecord(raw) : null;
@@ -165,9 +157,6 @@ export class AccessTokenManager {
     }
     async create(name, createdBy) {
         const normalizedName = normalizeName(name);
-        if (!this.storage.compareAndSet) {
-            throw new Error("Creating access tokens requires atomic compareAndSet storage");
-        }
         if (typeof createdBy !== "string" && !validIdentityReference(createdBy)) {
             throw new Error("Invalid token owner");
         }
@@ -184,12 +173,8 @@ export class AccessTokenManager {
             tokenHash: hash,
             tokenPrefix: token.slice(0, 12),
             createdAt: new Date().toISOString(),
-            createdBy: typeof createdBy === "string"
-                ? createdBy
-                : `${createdBy.namespace}:${createdBy.id}`,
-            ...(typeof createdBy === "string"
-                ? {}
-                : { principal: { ...createdBy } }),
+            createdBy: typeof createdBy === "string" ? createdBy : `${createdBy.namespace}:${createdBy.id}`,
+            ...(typeof createdBy === "string" ? {} : { principal: { ...createdBy } }),
         };
         try {
             await this.updateActive(record.id, true);
@@ -211,7 +196,7 @@ export class AccessTokenManager {
     }
     async rename(id, name) {
         const normalized = normalizeName(name);
-        const record = await this.updateRecord(id, current => ({ ...current, name: normalized }));
+        const record = await this.updateRecord(id, (current) => ({ ...current, name: normalized }));
         return record ? metadata(record) : null;
     }
     async revoke(id, revokedBy) {
@@ -221,11 +206,14 @@ export class AccessTokenManager {
         // Remove admission first. A metadata failure cannot leave a successful
         // revocation's lookup alive. Retry deletion even if already marked revoked.
         await this.storage.delete(lookupKey(record.tokenHash));
-        const updated = await this.updateRecord(id, current => current.revokedAt ? current : {
-            ...current, revokedAt: new Date().toISOString(), revokedBy,
-        });
-        if (this.storage.compareAndSet)
-            await this.updateActive(id, false);
+        const updated = await this.updateRecord(id, (current) => current.revokedAt
+            ? current
+            : {
+                ...current,
+                revokedAt: new Date().toISOString(),
+                revokedBy,
+            });
+        await this.updateActive(id, false);
         return updated ? metadata(updated) : null;
     }
     async updateRecord(id, update) {
@@ -239,45 +227,36 @@ export class AccessTokenManager {
             if (record.id !== id)
                 throw new Error("Stored access token id mismatch");
             const next = update(record);
-            if (this.storage.compareAndSet) {
-                // A rename racing revocation must retain revokedAt, including when
-                // an in-flight create has not yet published its lookup.
-                if (!await this.storage.compareAndSet(recordKey(id), raw, JSON.stringify(next)))
-                    continue;
-            }
-            else {
-                // Legacy adapters cannot create, so no late lookup writer exists.
-                // Revocation's deleted lookup still refuses a stale metadata write.
-                await this.storage.set(recordKey(id), JSON.stringify(next));
-            }
+            // A rename racing revocation must retain revokedAt, including when
+            // an in-flight create has not yet published its lookup.
+            if (!(await this.storage.compareAndSet(recordKey(id), raw, JSON.stringify(next))))
+                continue;
             return next;
         }
         throw new Error("Access token metadata is busy; retry the operation");
     }
     async updateActive(id, adding) {
-        const cas = this.storage.compareAndSet;
-        if (!cas)
-            throw new Error("Creating access tokens requires atomic compareAndSet storage");
         for (let attempt = 0; attempt < 32; attempt++) {
             const raw = await this.storage.get(ACTIVE_KEY);
             const ids = raw === null
-                ? (await this.list()).filter(token => !token.revokedAt).map(token => token.id)
+                ? (await this.list()).filter((token) => !token.revokedAt).map((token) => token.id)
                 : JSON.parse(raw);
-            if (!Array.isArray(ids) || !ids.every(value => typeof value === "string" && ID_RE.test(value)) || new Set(ids).size !== ids.length) {
+            if (!Array.isArray(ids) ||
+                !ids.every((value) => typeof value === "string" && ID_RE.test(value)) ||
+                new Set(ids).size !== ids.length) {
                 throw new Error("Stored access token capacity is invalid");
             }
             if (adding && ids.length >= this.maxActive)
                 throw new Error(`This deployment already has the maximum of ${this.maxActive} active access tokens`);
-            const next = adding ? [...ids, id] : ids.filter(value => value !== id);
-            if (await cas.call(this.storage, ACTIVE_KEY, raw, JSON.stringify(next)))
+            const next = adding ? [...ids, id] : ids.filter((value) => value !== id);
+            if (await this.storage.compareAndSet(ACTIVE_KEY, raw, JSON.stringify(next)))
                 return;
         }
         throw new Error("Access token capacity is busy; retry the operation");
     }
     async authorize(request) {
-        const header = request.headers.get("authorization") ?? "";
-        const match = /^Bearer\s+(.+)$/iu.exec(header);
-        const token = match?.[1];
+        const credential = authorizationCredential(request);
+        const token = credential.kind === "bearer" ? credential.token : undefined;
         if (!token || !TOKEN_VALUE_RE.test(token))
             return unauthorized();
         const hash = await hashToken(token);
@@ -298,8 +277,19 @@ export class AccessTokenManager {
         };
     }
 }
+/** The closed options accessTokens() accepts; see `assertKnownOptions`. */
+const ACCESS_TOKENS_OPTIONS = optionsOf()(keys("maxActive"));
 /** Opt in using the same storage namespace that held the v0.23 records. */
 export function accessTokens(storage, options = {}) {
+    options = assertKnownOptions(options, "accessTokens()", ACCESS_TOKENS_OPTIONS);
     const manager = new AccessTokenManager(storage, options);
-    return { auth: manager.auth, handle: context => routeAccessTokens(context, manager) };
+    const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
+    const optionSources = Object.freeze({
+        maxActive: options.maxActive === undefined ? "default" : "config",
+    });
+    return {
+        auth: manager.auth,
+        handle: (context) => routeAccessTokens(context, manager),
+        describe: () => ({ maxActive, optionSources }),
+    };
 }

package/dist/activity-request.js

@@ -0,0 +1,8 @@
+// Weak ownership keeps the grouping context within the request's lifetime.
+const requests = new WeakMap();
+export function bindActivityRequest(scope, context) {
+    requests.set(scope, context);
+}
+export function activityRequest(scope) {
+    return scope ? requests.get(scope) : undefined;
+}

package/dist/activity.d.ts

@@ -1,6 +1,11 @@
 import type { ActivityModule } from "./module-contracts.js";
-import type { CatalogDriftCounts, Logger } from "./types.js";
-export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
+import { type ClassificationCode } from "./errors.js";
+import type { Logger } from "./types.js";
+/** One policy for the record builder, SQL write/read boundaries, and UI. */
+export declare function activityClientFact(value: unknown, field: "name" | "version"): string | undefined;
+/** Stored package versions use a bounded release-version grammar, including prereleases. */
+export declare function activityPackageVersion(value: unknown): string | undefined;
+export type ActivityCallSource = "catalog_refresh" | "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
 export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled" | "paused" | "approved";
 /** Read-only history: how much one `resume_execution` approved (#672). */
 export type ActivityApproval = "call" | "tool";
@@ -28,11 +33,37 @@ export interface ActivityActor {
  * by construction. Deployments that need a safe human summary can add a
  * separate, explicit connector-level feature later.
  */
+export interface ActivityCatalogChange {
+    kind: "catalog_changed";
+    addedTools: number;
+    removedTools: number;
+    changedTools: number;
+}
+/** Integer metadata is checked at every write and read boundary. */
+export declare function activityCount(value: unknown): number | undefined;
+export declare function activityBehaviorFacts(event: {
+    classification?: unknown;
+    resultBytes?: unknown;
+    kind?: unknown;
+    drift?: unknown;
+    pool?: unknown;
+    actorBasis?: unknown;
+}): Pick<ToolCallActivityEvent, "classification" | "resultBytes" | "kind" | "drift" | "pool" | "actorBasis">;
 export interface ToolCallActivityEvent {
     schemaVersion: 1;
     id: string;
     occurredAt: string;
     requestId: string;
+    /** Absent on legacy tool rows. Catalog changes use the same paging envelope. */
+    kind?: "catalog_drift";
+    drift?: ActivityCatalogChange;
+    /** The final registry verdict captured when resolution succeeded. */
+    classification?: "read" | "write";
+    /** UTF-8 bytes of the downstream value before result paging or truncation. */
+    resultBytes?: number;
+    pool?: string;
+    /** Personal ownership is provable only for rows recorded from the admitted principal. */
+    actorBasis?: "principal";
     actor: ActivityActor;
     connectorId: string;
     toolName: string;
@@ -55,28 +86,13 @@ export interface ToolCallActivityEvent {
      * here — the approved arguments were never recorded.
      */
     approval?: ActivityApproval;
+    /** Real build version. Absent only in history written before telemetry existed. */
+    packageVersion?: string;
     serverName: string;
     serverVersion: string;
-    deploymentId?: string;
-}
-/**
- * A downstream catalog moved away from the manifest a release reviewed.
- *
- * Four integers and an id: the type has nowhere to put a tool name, a schema,
- * an argument, a result, or a downstream error string, which is the same
- * construction guarantee `ToolCallActivityEvent` makes. Which tool drifted is
- * deliberately absent — the runtime reports that something did, and the
- * maintainer-run check with a live catalog in front of it names names
- * ([#343](https://github.com/zackbart/connecta/issues/343),
- * [#351](https://github.com/zackbart/connecta/issues/351)).
- */
-export interface CatalogDriftActivityEvent extends CatalogDriftCounts {
-    schemaVersion: 1;
-    id: string;
-    occurredAt: string;
-    connectorId: string;
-    serverName: string;
-    serverVersion: string;
+    /** Self-declared client identity checked by activityClientFact; invalid facts are absent. */
+    clientName?: string;
+    clientVersion?: string;
     deploymentId?: string;
 }
 export interface ActivityPage {
@@ -97,13 +113,6 @@ export interface ActivityReadPage {
 /** Write-only deployments can implement only this small, vendor-neutral seam. */
 export interface ActivitySink {
     record(event: ToolCallActivityEvent): void | Promise<void>;
-    /**
-     * Optional catalog-drift channel. Optional rather than a widened `record`,
-     * because a store written before drift existed already decided what a row
-     * looks like: a sink that does not implement this simply never hears about
-     * drift, and the operator still reads the same counts from connector status.
-     */
-    recordCatalogDrift?(event: CatalogDriftActivityEvent): void | Promise<void>;
 }
 /** Optional read side used by Connecta's authenticated Activity UI. */
 export interface ActivityReader {
@@ -114,6 +123,14 @@ export interface ActivityReader {
 }
 export interface ActivityStore extends ActivitySink {
     list?: ActivityReader["list"];
+    /**
+     * The adapter and its retention, for `Connecta.describeConfig()`. Kinds
+     * other than the shipped `"d1"` and `"sqlite"` are described as `"custom"`.
+     */
+    describe?(): {
+        kind: string;
+        retentionDays?: number;
+    };
 }
 /** Reader implementations throw this for an opaque cursor they cannot decode. */
 export declare class InvalidActivityCursorError extends Error {
@@ -122,17 +139,21 @@ export declare class InvalidActivityCursorError extends Error {
 }
 export type ActivityReadGate = (actor: ActivityActor) => boolean | Promise<boolean>;
 /**
- * Deployment-scoped destination for drift observations. Not request-scoped:
- * a drifting catalog is something the deployment saw, not something a caller
- * did, so it carries no actor and no request id to attribute it to one.
+ * Default destination for catalog changes. Request attribution overrides it
+ * when a publication belongs to an admitted caller.
  */
 export interface CatalogDriftActivityContext {
-    recordDrift?: typeof recordCatalogDriftActivity;
+    recordChange?: typeof recordCatalogChangeActivity;
+    defer?: (promise: Promise<unknown>) => void;
     sink: ActivitySink;
     serverInfo: {
         name: string;
         version: string;
     };
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
     deploymentId?: string;
     logger: Logger;
 }
@@ -141,34 +162,47 @@ export interface ActivityRequestContext {
     recordTool?: typeof recordToolActivity | undefined;
     sink: ActivitySink;
     actor: ActivityActor;
+    /** Personal rows identify their admitted owner in the existing actor fields. */
+    principalActor?: ActivityActor;
     requestId: string;
+    pool?: string;
     serverInfo: {
         name: string;
         version: string;
     };
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
     deploymentId?: string;
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction">;
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "friction" | "classification" | "resultBytes" | "kind" | "drift"> & {
+    /**
+     * A code connecta assigns. Rows written by older deployments may hold
+     * others, so the stored event keeps `string`; a new row never does.
+     */
+    errorCode?: ClassificationCode;
+    personal?: boolean;
+    privateCatalog?: boolean;
+};
 /**
  * Best-effort by design: activity storage can never change a tool result.
  * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics
  * Engine complete inline; Node promises remain detached from the response.
  */
 export declare function recordToolActivity(context: ActivityRequestContext | undefined, input: ActivityEventInput): void;
-/**
- * Record one catalog-drift observation, best-effort like every other activity
- * write: a store that is down, or a sink that never implemented the channel,
- * can never change what a refresh returned to the caller who paid for it.
- */
-export declare function recordCatalogDriftActivity(context: CatalogDriftActivityContext | undefined, input: {
+/** A discrete catalog change, with no catalog names, descriptions or schemas. */
+export declare function recordCatalogChangeActivity(context: CatalogDriftActivityContext | undefined, input: {
     connectorId: string;
-} & CatalogDriftCounts): void;
+    drift: ActivityCatalogChange;
+    personal?: boolean;
+    privateCatalog?: boolean;
+}, request?: ActivityRequestContext): void;
 export interface ActivityHistoryOptions {
     store: ActivityStore;
     deploymentId?: string;
     readGate?: ActivityReadGate;
 }
-/** Attach payload-free history without changing tool results on store failure. */
 export declare function activityHistory(options: ActivityHistoryOptions): ActivityModule;

package/dist/activity.js

@@ -1,5 +1,8 @@
+import { CONNECTA_VERSION } from "./version.js";
+import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeActivity } from "./routes/activity.js";
-import { boundedEchoText } from "./errors.js";
+import { boundedEchoText, classificationCode } from "./errors.js";
+import { failureRecord, logFailure } from "./operator-record.js";
 /**
  * How long an identity field may be before the store stops believing it.
  *
@@ -15,10 +18,72 @@ import { boundedEchoText } from "./errors.js";
  * 40,000 would. The `…` marker keeps a clamped value from reading as a real one.
  */
 const MAX_ACTIVITY_NAME_BYTES = 128;
+/**
+ * Client facts use bounded ASCII grammars, never truncation or escaping.
+ * Names are 1 to 64 characters: alphanumeric or @ first (scoped package names
+ * such as `@modelcontextprotocol/inspector`), then alphanumerics, space, dot,
+ * underscore, @, /, + or -. Versions are 1 to 32 characters: alphanumeric
+ * first, then alphanumerics, dot, underscore, + or -. Prototype-key names are
+ * withheld too. The end assertion rejects even a final CR/LF, unlike `$`.
+ */
+const CLIENT_FACT_GRAMMARS = {
+    name: /^[A-Za-z0-9@][A-Za-z0-9 ._@/+-]{0,63}(?![\s\S])/,
+    version: /^[A-Za-z0-9][A-Za-z0-9._+-]{0,31}(?![\s\S])/,
+};
+const RESERVED_CLIENT_FACTS = new Set(["__proto__", "constructor", "prototype"]);
+/** One policy for the record builder, SQL write/read boundaries, and UI. */
+export function activityClientFact(value, field) {
+    return typeof value === "string" && !RESERVED_CLIENT_FACTS.has(value) && CLIENT_FACT_GRAMMARS[field].test(value)
+        ? value
+        : undefined;
+}
+/** Stored package versions use a bounded release-version grammar, including prereleases. */
+export function activityPackageVersion(value) {
+    return typeof value === "string" &&
+        value.length <= 128 &&
+        /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?(?![\s\S])/.test(value)
+        ? value
+        : undefined;
+}
 /** Two names and the dot between them. */
 const MAX_ACTIVITY_ADDRESS_BYTES = MAX_ACTIVITY_NAME_BYTES * 2 + 1;
 import { agentFrictionForCode } from "./activity-friction.js";
 export { agentFrictionForCode } from "./activity-friction.js";
+/** Integer metadata is checked at every write and read boundary. */
+export function activityCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+export function activityBehaviorFacts(event) {
+    const classification = event.classification === "read" || event.classification === "write" ? event.classification : undefined;
+    const resultBytes = activityCount(event.resultBytes);
+    const change = event.drift;
+    const drift = event.kind === "catalog_drift" &&
+        change?.kind === "catalog_changed" &&
+        activityCount(change.addedTools) !== undefined &&
+        activityCount(change.removedTools) !== undefined &&
+        activityCount(change.changedTools) !== undefined
+        ? {
+            kind: "catalog_changed",
+            addedTools: change.addedTools,
+            removedTools: change.removedTools,
+            changedTools: change.changedTools,
+        }
+        : undefined;
+    // Pool names come from matched deployment config, whose grammar has no size
+    // ceiling. Invalid stored scope stays withheld rather than becoming root scope.
+    const pool = event.pool === undefined || event.pool === null
+        ? undefined
+        : typeof event.pool === "string" && /^[a-z0-9_-]+(?![\s\S])/.test(event.pool)
+            ? event.pool
+            : "<withheld>";
+    return {
+        ...(event.actorBasis === "principal" ? { actorBasis: "principal" } : {}),
+        ...(classification !== undefined ? { classification } : {}),
+        ...(resultBytes !== undefined ? { resultBytes } : {}),
+        ...(drift ? { kind: "catalog_drift", drift } : {}),
+        ...(pool !== undefined ? { pool } : {}),
+    };
+}
 /** Reader implementations throw this for an opaque cursor they cannot decode. */
 export class InvalidActivityCursorError extends Error {
     name = "InvalidActivityCursorError";
@@ -36,13 +101,24 @@ export function recordToolActivity(context, input) {
         return;
     // A caller-supplied class wins because it knows something the code table
     // cannot: friction that belongs to a call which did not fail.
-    const friction = input.friction ?? agentFrictionForCode(input.errorCode);
+    // Checked here as well as by type: a handler can put any string in a
+    // `ConnectorCallError`'s code, and a downstream's own code is not recorded.
+    const errorCode = classificationCode(input.errorCode);
+    const friction = input.friction ?? agentFrictionForCode(errorCode);
+    // Re-check client grammars at the record boundary; never spread the envelope.
+    const clientName = activityClientFact(context.clientInfo?.name, "name");
+    const clientVersion = activityClientFact(context.clientInfo?.version, "version");
     const event = {
         schemaVersion: 1,
         id: crypto.randomUUID(),
         occurredAt: new Date().toISOString(),
         requestId: context.requestId,
-        actor: context.actor,
+        actor: input.personal || input.privateCatalog ? (context.principalActor ?? { kind: context.actor.kind }) : context.actor,
+        ...activityBehaviorFacts({
+            ...input,
+            pool: context.pool,
+            actorBasis: input.privateCatalog || (input.personal && context.principalActor) ? "principal" : undefined,
+        }),
         connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
         toolName: boundedEchoText(input.toolName, MAX_ACTIVITY_NAME_BYTES),
         address: boundedEchoText(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
@@ -50,13 +126,14 @@ export function recordToolActivity(context, input) {
         outcome: input.outcome,
         durationMs: Math.max(0, Math.trunc(input.durationMs)),
         attempts: Math.max(1, Math.trunc(input.attempts)),
-        ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+        ...(errorCode ? { errorCode } : {}),
         ...(friction ? { friction } : {}),
+        packageVersion: CONNECTA_VERSION,
         serverName: context.serverInfo.name,
         serverVersion: context.serverInfo.version,
-        ...(context.deploymentId
-            ? { deploymentId: context.deploymentId }
-            : {}),
+        ...(clientName !== undefined ? { clientName } : {}),
+        ...(clientVersion !== undefined ? { clientVersion } : {}),
+        ...(context.deploymentId ? { deploymentId: context.deploymentId } : {}),
     };
     try {
         const result = context.sink.record(event);
@@ -64,51 +141,42 @@ export function recordToolActivity(context, input) {
             return;
         }
         const pending = Promise.resolve(result).catch((error) => {
-            context.logger.warn("[connecta] activity record failed", error);
+            logFailure(context.logger, "activity record failed", failureRecord({}, error));
         });
         if (context.defer)
             context.defer(pending);
     }
     catch (error) {
-        context.logger.warn("[connecta] activity record failed", error);
+        logFailure(context.logger, "activity record failed", failureRecord({}, error));
     }
 }
-/**
- * Record one catalog-drift observation, best-effort like every other activity
- * write: a store that is down, or a sink that never implemented the channel,
- * can never change what a refresh returned to the caller who paid for it.
- */
-export function recordCatalogDriftActivity(context, input) {
-    if (!context?.sink.recordCatalogDrift)
+/** A discrete catalog change, with no catalog names, descriptions or schemas. */
+export function recordCatalogChangeActivity(context, input, request) {
+    if (!context)
         return;
-    const event = {
-        schemaVersion: 1,
-        id: crypto.randomUUID(),
-        occurredAt: new Date().toISOString(),
-        connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
-        unclassifiedTools: input.unclassifiedTools,
-        unservedTools: input.unservedTools,
-        annotationConflicts: input.annotationConflicts,
-        schemaChanges: input.schemaChanges,
-        serverName: context.serverInfo.name,
-        serverVersion: context.serverInfo.version,
-        ...(context.deploymentId ? { deploymentId: context.deploymentId } : {}),
-    };
-    try {
-        const result = context.sink.recordCatalogDrift(event);
-        if (!result || typeof result.then !== "function") {
-            return;
-        }
-        void Promise.resolve(result).catch((error) => {
-            context.logger.warn("[connecta] catalog drift record failed", error);
-        });
-    }
-    catch (error) {
-        context.logger.warn("[connecta] catalog drift record failed", error);
-    }
+    recordToolActivity(request ?? {
+        ...context,
+        actor: { kind: "system" },
+        requestId: crypto.randomUUID(),
+    }, {
+        connectorId: input.connectorId,
+        toolName: "<catalog>",
+        address: `${input.connectorId}.<catalog>`,
+        source: "catalog_refresh",
+        outcome: "success",
+        durationMs: 0,
+        attempts: 1,
+        kind: "catalog_drift",
+        drift: input.drift,
+        ...(input.personal ? { personal: true } : {}),
+        ...(input.privateCatalog ? { privateCatalog: true } : {}),
+    });
 }
 /** Attach payload-free history without changing tool results on store failure. */
+/** The closed options activityHistory() accepts; see `assertKnownOptions`. */
+const ACTIVITY_HISTORY_OPTIONS = optionsOf()(keys("store", "deploymentId", "readGate"));
 export function activityHistory(options) {
+    options = assertKnownOptions(options, "activityHistory()", ACTIVITY_HISTORY_OPTIONS);
     if (!options || typeof options.store?.record !== "function") {
         throw new Error("activityHistory.store must implement record(event)");
     }
@@ -116,6 +184,6 @@ export function activityHistory(options) {
         ...options,
         handle: routeActivity,
         recordTool: recordToolActivity,
-        recordDrift: recordCatalogDriftActivity,
+        recordChange: recordCatalogChangeActivity,
     };
 }