@openscout/protocol 0.2.63 → 0.2.82

package/dist/capability-matrix.js

@@ -0,0 +1,304 @@
+export function makeMcpToolCapabilityId(serverId, toolName) {
+    return `cap:mcp:${encodeURIComponent(serverId)}:tool:${encodeURIComponent(toolName)}`;
+}
+export function makeModelCapabilityId(providerId, modelId) {
+    return `cap:model:${encodeURIComponent(providerId)}:${encodeURIComponent(modelId)}`;
+}
+export function inferMcpToolEffects(annotations) {
+    const effects = [];
+    if (annotations?.readOnlyHint === true) {
+        effects.push("read");
+    }
+    if (annotations?.destructiveHint === true) {
+        effects.push("write");
+    }
+    if (annotations?.openWorldHint === true) {
+        effects.push("network");
+    }
+    return effects.length > 0 ? effects : ["unknown"];
+}
+export function normalizeMcpToolsToScoutCapabilities(options) {
+    const capturedAt = options.capturedAt ?? Date.now();
+    const tools = getMcpToolDefinitions(options.tools);
+    const evidence = buildMcpDiscoveryEvidence(options, capturedAt);
+    return tools
+        .filter((tool) => typeof tool.name === "string" && tool.name.trim().length > 0)
+        .map((tool) => {
+        const toolName = tool.name.trim();
+        const annotations = tool.annotations;
+        const effects = inferMcpToolEffects(annotations);
+        const methodHints = buildMcpMethodHints(annotations);
+        const readinessEvidence = [
+            evidence,
+            ...(options.readiness?.evidence ?? []),
+        ];
+        return {
+            id: makeMcpToolCapabilityId(options.serverId, toolName),
+            name: `mcp.${options.serverId}.${toolName}`,
+            displayName: tool.title ?? annotations?.title ?? toolName,
+            description: tool.description,
+            provider: "mcp",
+            providerId: options.serverId,
+            methods: [{
+                    name: "call",
+                    displayName: tool.title ?? annotations?.title ?? toolName,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
+                    effects,
+                    idempotent: inferMcpIdempotence(annotations),
+                    requiresApproval: annotations?.destructiveHint === true ? true : undefined,
+                    hints: methodHints,
+                    metadata: {
+                        mcpToolName: toolName,
+                    },
+                }],
+            scope: options.scope,
+            readiness: {
+                state: "unknown",
+                detail: "Discovered from MCP tools/list; runtime readiness has not been probed.",
+                checkedAt: capturedAt,
+                ...options.readiness,
+                evidence: readinessEvidence,
+            },
+            enforcement: {
+                level: "mcp_server",
+                trust: "advisory",
+                reason: "MCP tool metadata and annotations are advisory; Scout policy still decides availability.",
+            },
+            provenance: {
+                sourceKind: "mcp_server",
+                sourceId: options.serverId,
+                sourceName: options.serverName,
+                capturedAt,
+                protocol: "mcp",
+                protocolVersion: options.protocolVersion,
+                evidence: [evidence],
+            },
+            enabled: options.enabled ?? true,
+            metadata: {
+                mcpServerCapabilities: options.serverCapabilities,
+                mcpTool: {
+                    name: toolName,
+                    icons: tool.icons,
+                    meta: tool._meta,
+                },
+            },
+        };
+    });
+}
+export function buildMcpCapabilityMatrixSnapshot(options) {
+    const generatedAt = options.capturedAt ?? Date.now();
+    const capabilities = normalizeMcpToolsToScoutCapabilities({
+        ...options,
+        capturedAt: generatedAt,
+    });
+    return {
+        generatedAt,
+        scope: options.scope,
+        sources: [{
+                kind: "mcp_server",
+                id: options.serverId,
+                name: options.serverName,
+                capturedAt: generatedAt,
+                protocol: "mcp",
+                protocolVersion: options.protocolVersion,
+                raw: {
+                    capabilities: options.serverCapabilities,
+                    tools: options.tools,
+                },
+            }],
+        capabilities,
+        warnings: [],
+    };
+}
+export function normalizeModelCatalogToScoutCapabilities(options) {
+    const capturedAt = options.capturedAt ?? Date.now();
+    const evidence = {
+        kind: "catalog",
+        ref: `model-catalog:${options.sourceId}`,
+        sourceId: options.sourceId,
+        observedAt: capturedAt,
+        trust: "declared",
+    };
+    return options.models
+        .filter((model) => model.providerId.trim() && model.modelId.trim())
+        .map((model) => {
+        const providerId = model.providerId.trim();
+        const modelId = model.modelId.trim();
+        return {
+            id: makeModelCapabilityId(providerId, modelId),
+            name: `model.${providerId}.${modelId}`,
+            displayName: model.displayName ?? modelId,
+            provider: "model",
+            providerId,
+            methods: [{
+                    name: "invoke",
+                    displayName: "Invoke model",
+                    effects: ["execute"],
+                    metadata: {
+                        inputModalities: model.inputModalities ?? ["unknown"],
+                        outputModalities: model.outputModalities ?? ["unknown"],
+                        features: model.features ?? {},
+                        contextWindowTokens: model.contextWindowTokens,
+                        maxOutputTokens: model.maxOutputTokens,
+                    },
+                }],
+            scope: options.scope,
+            readiness: {
+                state: "unknown",
+                detail: "Declared by model catalog; provider readiness has not been probed.",
+                checkedAt: capturedAt,
+                evidence: [evidence],
+            },
+            enforcement: {
+                level: "remote_authority",
+                trust: "declared",
+                reason: "Model metadata is catalog-declared; Scout must still verify provider readiness and policy.",
+            },
+            provenance: {
+                sourceKind: "model_catalog",
+                sourceId: options.sourceId,
+                sourceName: options.sourceName,
+                capturedAt,
+                evidence: [evidence],
+            },
+            enabled: options.enabled ?? true,
+            metadata: {
+                model: {
+                    providerId,
+                    modelId,
+                    inputModalities: model.inputModalities ?? ["unknown"],
+                    outputModalities: model.outputModalities ?? ["unknown"],
+                    features: model.features ?? {},
+                    contextWindowTokens: model.contextWindowTokens,
+                    maxOutputTokens: model.maxOutputTokens,
+                    metadata: model.metadata,
+                },
+            },
+        };
+    });
+}
+export function evaluateScoutCapabilityAvailability(snapshot, options) {
+    const capability = snapshot.capabilities.find((candidate) => candidate.id === options.capabilityId);
+    if (!capability) {
+        return {
+            decision: "deny",
+            capabilityId: options.capabilityId,
+            reason: "capability_missing",
+            detail: "Capability is not present in the current matrix snapshot.",
+        };
+    }
+    if (!capability.enabled) {
+        return {
+            decision: "deny",
+            capabilityId: capability.id,
+            reason: "capability_disabled",
+            detail: "Capability is disabled in the current matrix snapshot.",
+        };
+    }
+    const methodName = options.methodName ?? capability.methods[0]?.name;
+    const method = methodName ? capability.methods.find((candidate) => candidate.name === methodName) : undefined;
+    if (!methodName || !method) {
+        return {
+            decision: "deny",
+            capabilityId: capability.id,
+            methodName,
+            reason: "method_missing",
+            detail: "Requested method is not present on the capability.",
+        };
+    }
+    if (method.requiresApproval) {
+        return {
+            decision: "require_approval",
+            capabilityId: capability.id,
+            methodName,
+            reason: "method_requires_approval",
+            detail: "Capability method requires operator approval before execution.",
+        };
+    }
+    switch (capability.readiness.state) {
+        case "ready":
+            return {
+                decision: "allow",
+                capabilityId: capability.id,
+                methodName,
+                reason: "Capability is ready.",
+            };
+        case "degraded":
+            return {
+                decision: "downgrade",
+                capabilityId: capability.id,
+                methodName,
+                reason: "readiness_degraded",
+                detail: capability.readiness.detail ?? "Capability readiness is degraded.",
+            };
+        case "missing":
+            return {
+                decision: "deny",
+                capabilityId: capability.id,
+                methodName,
+                reason: "readiness_missing",
+                detail: capability.readiness.detail ?? "Capability readiness is missing.",
+            };
+        case "disabled":
+            return {
+                decision: "deny",
+                capabilityId: capability.id,
+                methodName,
+                reason: "readiness_disabled",
+                detail: capability.readiness.detail ?? "Capability readiness is disabled.",
+            };
+        case "unknown":
+            if (options.requireReady === false) {
+                return {
+                    decision: "allow",
+                    capabilityId: capability.id,
+                    methodName,
+                    reason: "Capability readiness is unknown but this check does not require ready state.",
+                };
+            }
+            return {
+                decision: "unknown",
+                capabilityId: capability.id,
+                methodName,
+                reason: "readiness_unknown",
+                detail: capability.readiness.detail ?? "Capability readiness is unknown.",
+            };
+    }
+}
+function getMcpToolDefinitions(tools) {
+    return isMcpToolDefinitionArray(tools) ? tools : tools.tools ?? [];
+}
+function isMcpToolDefinitionArray(value) {
+    return Array.isArray(value);
+}
+function buildMcpDiscoveryEvidence(options, observedAt) {
+    return {
+        kind: "protocol_discovery",
+        ref: `mcp:${options.serverId}:tools/list`,
+        sourceId: options.serverId,
+        observedAt,
+        protocol: "mcp",
+        protocolVersion: options.protocolVersion,
+        trust: "declared",
+    };
+}
+function buildMcpMethodHints(annotations) {
+    if (!annotations) {
+        return undefined;
+    }
+    return {
+        readOnly: annotations.readOnlyHint,
+        destructive: annotations.destructiveHint,
+        idempotent: annotations.idempotentHint,
+        openWorld: annotations.openWorldHint,
+        annotationsTrusted: false,
+    };
+}
+function inferMcpIdempotence(annotations) {
+    if (annotations?.idempotentHint !== undefined) {
+        return annotations.idempotentHint;
+    }
+    return annotations?.readOnlyHint === true ? true : undefined;
+}

package/dist/channel-identity.d.ts

@@ -0,0 +1,40 @@
+import type { MetadataMap, ScoutId } from "./common.js";
+export type ConversationIdentityRecord = {
+    id: ScoutId;
+    kind: string;
+    metadata?: MetadataMap;
+};
+export declare const CHANNEL_ID_PREFIX = "chn-";
+export declare const CHAT_ID_PREFIX = "chn-";
+export declare const LEGACY_CHAT_ID_PREFIX = "chat_";
+export declare const LEGACY_CHANNEL_ID_PREFIX = "c.";
+export declare const CHANNEL_NATURAL_KEY_METADATA = "naturalKey";
+export declare function mintChannelId(randomUuid: () => string): ScoutId;
+/**
+ * Mint the opaque id for a named/system channel from its canonical identity.
+ * Every concurrent creator therefore arrives at the same broker record even
+ * when each caller began from a stale snapshot.
+ */
+export declare function stableChannelId(naturalKey: string): ScoutId;
+export declare function isOpaqueChannelId(value: string | null | undefined): value is ScoutId;
+export declare function directChannelNaturalKey(participantIds: ScoutId[]): string;
+export declare function namedChannelNaturalKey(channel: string): string;
+export declare function systemChannelNaturalKey(name: string): string;
+export declare function channelNaturalKeyFromMetadata(metadata: MetadataMap | undefined): string | null;
+/**
+ * Read the semantic identity of a conversation, including the structural ids
+ * written by Scout versions that predate `metadata.naturalKey`.
+ *
+ * Structural ids remain read-only compatibility aliases. New writes must use
+ * an opaque id and persist the natural key in metadata.
+ */
+export declare function conversationNaturalKey(conversation: ConversationIdentityRecord): string | null;
+/**
+ * Return every record for one semantic conversation in deterministic priority
+ * order: the stable named-channel id, another opaque id, then structural
+ * compatibility aliases. This prevents snapshot insertion order from choosing
+ * which chat receives a write.
+ */
+export declare function conversationsWithNaturalKey<T extends ConversationIdentityRecord>(conversations: Iterable<T>, naturalKey: string): T[];
+export declare function preferredConversationWithNaturalKey<T extends ConversationIdentityRecord>(conversations: Iterable<T>, naturalKey: string): T | undefined;
+//# sourceMappingURL=channel-identity.d.ts.map

package/dist/channel-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-identity.d.ts","sourceRoot":"","sources":["../src/channel-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,0BAA0B,GAAG;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,iBAAiB,SAAS,CAAC;AACxC,eAAO,MAAM,cAAc,SAAoB,CAAC;AAChD,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAC7C,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,MAAM,GAAG,OAAO,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAW3D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,OAAO,CAWpF;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,OAAO,EAAE,GAAG,MAAM,CAEzE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,WAAW,GAAG,SAAS,GAChC,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,0BAA0B,GACvC,MAAM,GAAG,IAAI,CAwBf;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,0BAA0B,EAC9E,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,CAAC,EAAE,CAeL;AAED,wBAAgB,mCAAmC,CAAC,CAAC,SAAS,0BAA0B,EACtF,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,CAAC,GAAG,SAAS,CAEf"}

package/dist/channel-identity.js

@@ -0,0 +1,108 @@
+export const CHANNEL_ID_PREFIX = "chn-";
+export const CHAT_ID_PREFIX = CHANNEL_ID_PREFIX;
+export const LEGACY_CHAT_ID_PREFIX = "chat_";
+export const LEGACY_CHANNEL_ID_PREFIX = "c.";
+export const CHANNEL_NATURAL_KEY_METADATA = "naturalKey";
+export function mintChannelId(randomUuid) {
+    return `${CHAT_ID_PREFIX}${randomUuid().toLowerCase().replace(/-/g, "")}`;
+}
+/**
+ * Mint the opaque id for a named/system channel from its canonical identity.
+ * Every concurrent creator therefore arrives at the same broker record even
+ * when each caller began from a stale snapshot.
+ */
+export function stableChannelId(naturalKey) {
+    const normalized = naturalKey.trim().toLowerCase();
+    const hash = (seed) => {
+        let value = seed;
+        for (let index = 0; index < normalized.length; index += 1) {
+            value ^= BigInt(normalized.charCodeAt(index));
+            value = BigInt.asUintN(64, value * 0x100000001b3n);
+        }
+        return value.toString(16).padStart(16, "0");
+    };
+    return `${CHAT_ID_PREFIX}${hash(0xcbf29ce484222325n)}${hash(0x84222325cbf29ce4n)}`;
+}
+export function isOpaqueChannelId(value) {
+    if (typeof value !== "string")
+        return false;
+    return (value.startsWith(CHAT_ID_PREFIX) && value.length > CHAT_ID_PREFIX.length) || (value.startsWith(LEGACY_CHAT_ID_PREFIX)
+        && value.length > LEGACY_CHAT_ID_PREFIX.length) || (value.startsWith(LEGACY_CHANNEL_ID_PREFIX)
+        && value.length > LEGACY_CHANNEL_ID_PREFIX.length);
+}
+export function directChannelNaturalKey(participantIds) {
+    return `direct:${stableIdentityParts(participantIds).join(",")}`;
+}
+export function namedChannelNaturalKey(channel) {
+    return `channel:${encodeIdentityPart(channel.trim().toLowerCase() || "shared")}`;
+}
+export function systemChannelNaturalKey(name) {
+    return `system:${encodeIdentityPart(name.trim().toLowerCase() || "system")}`;
+}
+export function channelNaturalKeyFromMetadata(metadata) {
+    const value = metadata?.[CHANNEL_NATURAL_KEY_METADATA];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+/**
+ * Read the semantic identity of a conversation, including the structural ids
+ * written by Scout versions that predate `metadata.naturalKey`.
+ *
+ * Structural ids remain read-only compatibility aliases. New writes must use
+ * an opaque id and persist the natural key in metadata.
+ */
+export function conversationNaturalKey(conversation) {
+    const explicit = channelNaturalKeyFromMetadata(conversation.metadata);
+    if (explicit) {
+        return explicit;
+    }
+    if (conversation.kind !== "channel" && conversation.kind !== "system") {
+        return null;
+    }
+    const metadataChannel = conversation.metadata?.channel;
+    const legacyChannel = conversation.id.startsWith("channel.")
+        ? conversation.id.slice("channel.".length)
+        : null;
+    const channel = typeof metadataChannel === "string" && metadataChannel.trim()
+        ? metadataChannel.trim()
+        : legacyChannel?.trim() || null;
+    if (!channel) {
+        return null;
+    }
+    return conversation.kind === "system"
+        ? systemChannelNaturalKey(channel)
+        : namedChannelNaturalKey(channel);
+}
+/**
+ * Return every record for one semantic conversation in deterministic priority
+ * order: the stable named-channel id, another opaque id, then structural
+ * compatibility aliases. This prevents snapshot insertion order from choosing
+ * which chat receives a write.
+ */
+export function conversationsWithNaturalKey(conversations, naturalKey) {
+    const normalizedNaturalKey = naturalKey.trim();
+    const stableId = normalizedNaturalKey.startsWith("channel:")
+        || normalizedNaturalKey.startsWith("system:")
+        ? stableChannelId(normalizedNaturalKey)
+        : null;
+    const priority = (conversation) => {
+        if (stableId && conversation.id === stableId)
+            return 0;
+        if (isOpaqueChannelId(conversation.id))
+            return 1;
+        return 2;
+    };
+    return [...conversations]
+        .filter((conversation) => conversationNaturalKey(conversation) === normalizedNaturalKey)
+        .sort((left, right) => priority(left) - priority(right) || left.id.localeCompare(right.id));
+}
+export function preferredConversationWithNaturalKey(conversations, naturalKey) {
+    return conversationsWithNaturalKey(conversations, naturalKey)[0];
+}
+function stableIdentityParts(values) {
+    return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)))
+        .sort()
+        .map(encodeIdentityPart);
+}
+function encodeIdentityPart(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}

package/dist/collaboration.d.ts

@@ -1,9 +1,9 @@
 import type { MetadataMap, ScoutId } from "./common.js";
-export type CollaborationKind = "question" | "work_item";
+export type CollaborationKind = "work_item" | "question";
 export type CollaborationPriority = "low" | "normal" | "high" | "urgent";
 export type CollaborationAcceptanceState = "none" | "pending" | "accepted" | "reopened";
-export type QuestionState = "open" | "answered" | "closed" | "declined";
 export type WorkItemState = "open" | "working" | "waiting" | "review" | "done" | "cancelled";
+export type QuestionState = "open" | "answered" | "closed" | "declined";
 export type CollaborationRelationKind = "blocks" | "spawns" | "relates_to" | "references";
 export interface CollaborationRelation {
     kind: CollaborationRelationKind;
@@ -11,7 +11,7 @@ export interface CollaborationRelation {
     metadata?: MetadataMap;
 }
 export interface CollaborationWaitingOn {
-    kind: "actor" | "question" | "work_item" | "approval" | "artifact" | "condition";
+    kind: "actor" | "work_item" | "approval" | "artifact" | "condition";
     label: string;
     targetId?: ScoutId;
     metadata?: MetadataMap;
@@ -40,16 +40,6 @@ export interface CollaborationRecordBase {
     updatedAt: number;
     metadata?: MetadataMap;
 }
-export interface QuestionRecord extends CollaborationRecordBase {
-    kind: "question";
-    state: QuestionState;
-    acceptanceState: CollaborationAcceptanceState;
-    askedById?: ScoutId;
-    askedOfId?: ScoutId;
-    answerMessageId?: ScoutId;
-    spawnedWorkItemId?: ScoutId;
-    closedAt?: number;
-}
 export interface WorkItemRecord extends CollaborationRecordBase {
     kind: "work_item";
     state: WorkItemState;
@@ -61,8 +51,29 @@ export interface WorkItemRecord extends CollaborationRecordBase {
     reviewRequestedAt?: number;
     completedAt?: number;
 }
-export type CollaborationRecord = QuestionRecord | WorkItemRecord;
-export type CollaborationEventKind = "created" | "claimed" | "answered" | "accepted" | "reopened" | "waiting" | "progressed" | "handoff" | "review_requested" | "done" | "declined" | "cancelled";
+/**
+ * A lightweight information-seeking interaction. A peer of {@link WorkItemRecord},
+ * not a point on the same severity ladder: a question can resolve directly, attach
+ * to a work item, or spawn one.
+ *
+ * Acceptance is modeled separately from workflow state (via `acceptanceState`) so a
+ * reply and satisfaction do not collapse into one transition — a question can be
+ * `answered` without yet being `closed`.
+ */
+export interface QuestionRecord extends CollaborationRecordBase {
+    kind: "question";
+    state: QuestionState;
+    acceptanceState: CollaborationAcceptanceState;
+    /** The actor being asked to answer. */
+    askedById?: ScoutId;
+    answeredById?: ScoutId;
+    /** The delivered answer text, present once `state` is `answered`. */
+    answer?: string;
+    answeredAt?: number;
+    closedAt?: number;
+}
+export type CollaborationRecord = WorkItemRecord | QuestionRecord;
+export type CollaborationEventKind = "created" | "claimed" | "accepted" | "reopened" | "waiting" | "progressed" | "handoff" | "review_requested" | "done" | "dismissed" | "cancelled";
 export interface CollaborationEvent {
     id: ScoutId;
     recordId: ScoutId;
@@ -73,8 +84,25 @@ export interface CollaborationEvent {
     summary?: string;
     metadata?: MetadataMap;
 }
-export declare function isQuestionTerminalState(state: QuestionState): boolean;
 export declare function isWorkItemTerminalState(state: WorkItemState): boolean;
+/**
+ * A question is terminal once it is `closed` or `declined`. `answered` is NOT terminal
+ * — acceptance is tracked separately, so an answered question may still await closure.
+ */
+export declare function isQuestionTerminalState(state: QuestionState): boolean;
+/** Terminal-state check across both collaboration kinds. */
+export declare function isCollaborationTerminalState(record: CollaborationRecord): boolean;
+/** Narrow a {@link CollaborationRecord} to a {@link WorkItemRecord}. */
+export declare function isWorkItem(record: CollaborationRecord): record is WorkItemRecord;
+/** Narrow a {@link CollaborationRecord} to a {@link QuestionRecord}. */
+export declare function isQuestion(record: CollaborationRecord): record is QuestionRecord;
+/**
+ * The actor a collaboration record is directed at / awaiting acceptance from: the
+ * `requestedById` for a work item, the `askedById` for a question. Consumers that
+ * route or attribute a record by its requester should use this rather than reaching
+ * for a kind-specific field, so questions are handled instead of silently dropped.
+ */
+export declare function collaborationRequesterId(record: CollaborationRecord): ScoutId | undefined;
 export declare function collaborationRequiresNextMoveOwner(record: CollaborationRecord): boolean;
 export declare function collaborationRequiresOwner(record: CollaborationRecord): boolean;
 export declare function collaborationRequiresWaitingOn(record: CollaborationRecord): boolean;
@@ -83,3 +111,4 @@ export declare function validateCollaborationRecord(record: CollaborationRecord)
 export declare function assertValidCollaborationRecord(record: CollaborationRecord): void;
 export declare function validateCollaborationEvent(event: CollaborationEvent, record?: CollaborationRecord): string[];
 export declare function assertValidCollaborationEvent(event: CollaborationEvent, record?: CollaborationRecord): void;
+//# sourceMappingURL=collaboration.d.ts.map

package/dist/collaboration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collaboration.d.ts","sourceRoot":"","sources":["../src/collaboration.ts"],"names":[],"mappings":"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"}

package/dist/collaboration.js

@@ -1,14 +1,38 @@
+export function isWorkItemTerminalState(state) {
+    return state === "done" || state === "cancelled";
+}
+/**
+ * A question is terminal once it is `closed` or `declined`. `answered` is NOT terminal
+ * — acceptance is tracked separately, so an answered question may still await closure.
+ */
 export function isQuestionTerminalState(state) {
     return state === "closed" || state === "declined";
 }
-export function isWorkItemTerminalState(state) {
-    return state === "done" || state === "cancelled";
+/** Terminal-state check across both collaboration kinds. */
+export function isCollaborationTerminalState(record) {
+    return record.kind === "work_item"
+        ? isWorkItemTerminalState(record.state)
+        : isQuestionTerminalState(record.state);
+}
+/** Narrow a {@link CollaborationRecord} to a {@link WorkItemRecord}. */
+export function isWorkItem(record) {
+    return record.kind === "work_item";
+}
+/** Narrow a {@link CollaborationRecord} to a {@link QuestionRecord}. */
+export function isQuestion(record) {
+    return record.kind === "question";
+}
+/**
+ * The actor a collaboration record is directed at / awaiting acceptance from: the
+ * `requestedById` for a work item, the `askedById` for a question. Consumers that
+ * route or attribute a record by its requester should use this rather than reaching
+ * for a kind-specific field, so questions are handled instead of silently dropped.
+ */
+export function collaborationRequesterId(record) {
+    return isWorkItem(record) ? record.requestedById : record.askedById;
 }
 export function collaborationRequiresNextMoveOwner(record) {
-    if (record.kind === "question") {
-        return !isQuestionTerminalState(record.state);
-    }
-    return !isWorkItemTerminalState(record.state);
+    return !isCollaborationTerminalState(record);
 }
 export function collaborationRequiresOwner(record) {
     return record.kind === "work_item" && !isWorkItemTerminalState(record.state);
@@ -20,10 +44,7 @@ export function collaborationRequiresAcceptance(record) {
     if (record.acceptanceState === "none") {
         return false;
     }
-    if (record.kind === "question") {
-        return Boolean(record.askedById && record.askedOfId);
-    }
-    return Boolean(record.requestedById);
+    return Boolean(collaborationRequesterId(record));
 }
 export function validateCollaborationRecord(record) {
     const errors = [];
@@ -51,14 +72,14 @@ export function validateCollaborationRecord(record) {
     if (record.kind === "work_item" && collaborationRequiresWaitingOn(record) && !record.waitingOn) {
         errors.push("waiting work items require waitingOn");
     }
-    if (record.kind === "question") {
-        if (record.spawnedWorkItemId && record.spawnedWorkItemId === record.id) {
-            errors.push("question spawnedWorkItemId cannot reference the question itself");
-        }
-    }
-    else if (record.waitingOn?.targetId && record.waitingOn.targetId === record.id) {
+    if (record.kind === "work_item"
+        && record.waitingOn?.targetId
+        && record.waitingOn.targetId === record.id) {
         errors.push("waitingOn.targetId cannot reference the work item itself");
     }
+    if (record.kind === "question" && record.state === "answered" && !record.answer?.trim()) {
+        errors.push("answered questions require an answer");
+    }
     if (record.acceptanceState !== "none" && !collaborationRequiresAcceptance(record)) {
         errors.push("acceptanceState requires the corresponding requester and reviewer identities");
     }
@@ -89,17 +110,12 @@ export function validateCollaborationEvent(event, record) {
             errors.push("collaboration event recordKind does not match the target record");
         }
     }
-    if (event.kind === "answered" && event.recordKind !== "question") {
-        errors.push("answered events only apply to questions");
-    }
-    if (event.kind === "declined" && event.recordKind !== "question") {
-        errors.push("declined events only apply to questions");
-    }
     if ((event.kind === "waiting"
         || event.kind === "progressed"
         || event.kind === "review_requested"
         || event.kind === "done"
-        || event.kind === "cancelled")
+        || event.kind === "cancelled"
+        || event.kind === "claimed")
         && event.recordKind !== "work_item") {
         errors.push(`${event.kind} events only apply to work items`);
     }