castle-web-sdk 0.4.33 → 0.4.34

package/dist/server/storage.d.ts

@@ -102,17 +102,57 @@ export interface CompleteCharacterBeatInput {
     eventOccurrenceId: string;
     outcomeId: string;
 }
+export interface EvaluateCharacterInformationInput {
+    operationId: string;
+    maxDeliveries?: number;
+}
+export interface CharacterInformationEvaluationResult {
+    generation: number;
+    evaluatedAt: string;
+    snapshotCandidateCount: number;
+    deliveries: Array<{
+        ruleId: string;
+        rootId: string;
+        recipientCharacterId: string;
+        status: "delivered" | "already_known";
+    }>;
+    cancelled: Array<{
+        ruleId: string;
+        rootId: string;
+    }>;
+    blocked: Array<{
+        ruleId: string;
+        rootId: string;
+        recipientCharacterId: string;
+        code: "testimony_backlog_full" | "information_limit" | "storage_capacity";
+    }>;
+    remainingCount: number;
+}
+export type CharacterInformationEvaluationOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterInformationEvaluationResult | null;
+};
+export interface SendCharacterInput {
+    operationId: string;
+    characterId: string;
+    input: string;
+    audience: {
+        listenerCharacterIds: string[];
+    };
+}
 /**
  * Narrative commands do not run a model. They record creator-validated events,
  * knowledge delivery and beat completion inside this immutable playthrough.
  */
 export interface ServerPlaythroughCharacters {
+    /** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
+    send(input: SendCharacterInput): Promise<CharacterOperation>;
     recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
     setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
     shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
     inspect(): Promise<Json>;
     deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
     completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
+    evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
     status(operationId: string): Promise<CharacterOperation>;
     history(options?: ServerCharacterHistoryOptions): Promise<CharacterHistory>;
 }

package/dist/server/storage.js

@@ -84,6 +84,17 @@ export function createServerStorage(platformHandle) {
 }
 function createPlaythrough(call, subject, generation) {
     const characters = Object.freeze({
+        async send(input) {
+            const characterId = assertNarrativeId(input?.characterId, "characterId");
+            return call("characterSendWithAudience", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                characterId,
+                input: assertCharacterInput(input?.input),
+                audience: assertCharacterAudience(input?.audience, characterId),
+            });
+        },
         async recordEvent(input) {
             return call("characterRecordEvent", {
                 subject,
@@ -139,6 +150,15 @@ function createPlaythrough(call, subject, generation) {
                 outcomeId: assertNarrativeId(input?.outcomeId, "outcomeId"),
             });
         },
+        async evaluateInformation(input) {
+            const maxDeliveries = assertInformationMaxDeliveries(input?.maxDeliveries);
+            return call("characterEvaluateInformation", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                ...(maxDeliveries === undefined ? {} : { maxDeliveries }),
+            });
+        },
         async status(operationId) {
             return call("characterStatus", {
                 subject,
@@ -351,6 +371,33 @@ function assertNarrativeIds(value, field) {
     }
     return value.map((item) => assertNarrativeId(item, field));
 }
+function assertCharacterInput(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 2000 ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value)) {
+        throw characterArgumentError("input must be valid non-empty text of at most 2000 characters.");
+    }
+    return value;
+}
+function assertCharacterAudience(value, targetCharacterId) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw characterArgumentError("audience must contain listenerCharacterIds.");
+    }
+    const audience = value;
+    if (Object.keys(audience).some((key) => key !== "listenerCharacterIds") ||
+        !Array.isArray(audience.listenerCharacterIds) ||
+        audience.listenerCharacterIds.length > 3) {
+        throw characterArgumentError("audience must contain at most three listener character ids.");
+    }
+    const listenerCharacterIds = audience.listenerCharacterIds.map((id) => assertNarrativeId(id, "audience.listenerCharacterIds"));
+    if (new Set(listenerCharacterIds).size !== listenerCharacterIds.length ||
+        listenerCharacterIds.includes(targetCharacterId)) {
+        throw characterArgumentError("audience listeners must be unique and must not include the target character.");
+    }
+    return { listenerCharacterIds };
+}
 function assertKnowledgeSource(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", "source must name creator_event or a character.", "session.storage.playthrough.characters.deliverKnowledge");
@@ -402,6 +449,14 @@ function assertStateRevision(value) {
     }
     return value;
 }
+function assertInformationMaxDeliveries(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 32) {
+        throw characterArgumentError("maxDeliveries must be an integer from 1 through 32.");
+    }
+    return value;
+}
 function assertStateChanges(value, hasObjectChanges = false) {
     if (!Array.isArray(value) || value.length > 32 || (!hasObjectChanges && value.length < 1)) {
         throw characterArgumentError(hasObjectChanges

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.33",
+  "version": "0.4.34",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"