@ifsoul/core 0.4.0 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ compose these public artifacts. See [repository ownership](https://github.com/op
 Use Node.js 22.18–24 and an ESM project:
 
 ```sh
-npm install @ifsoul/core@0.4.0
+npm install @ifsoul/core@0.5.0
 ```
 
 The package includes compiled JavaScript and TypeScript declarations. Import the
@@ -62,3 +62,6 @@ pnpm build
 See [development](https://github.com/openifsoul/core/blob/main/docs/development.md),
 [architecture](https://github.com/openifsoul/core/blob/main/docs/architecture.md)
 and [contribution](https://github.com/openifsoul/core/blob/main/CONTRIBUTING.md).
+
+See [behavior configuration and dynamic parameters](docs/behavior.md) for shared goals,
+reaction policy and evidence-linked state.

package/dist/packages/protocol/src/index.d.ts

@@ -6,6 +6,6 @@ export declare function canonical(value: unknown): string;
 export { resolveResourceLimits, BUFFERED_JSON_MAX_BYTES, MAX_TIMER_MS, } from "./resource-policy.js";
 export type { BudgetReport } from "./resource-policy.js";
 /** Current train identifier; wire families require exact kind/version validation. */
-export declare const IFSOUL_VERSION: "0.4.0";
+export declare const IFSOUL_VERSION: "0.5.0";
 /** Structural current ModelProvider spec validation; not a provider wire transport. */
 export declare function validateModelProviderDocument(value: unknown): boolean;

package/dist/packages/protocol/src/index.js

@@ -47,7 +47,7 @@ export function canonical(value) {
 }
 export { resolveResourceLimits, BUFFERED_JSON_MAX_BYTES, MAX_TIMER_MS, } from "./resource-policy.js";
 /** Current train identifier; wire families require exact kind/version validation. */
-export const IFSOUL_VERSION = "0.4.0";
+export const IFSOUL_VERSION = "0.5.0";
 /** Structural current ModelProvider spec validation; not a provider wire transport. */
 export function validateModelProviderDocument(value) {
     return validators.current_provider(value) === true;

package/dist/packages/runtime/src/behavior-types.d.ts

@@ -0,0 +1,150 @@
+export type BehaviorPermission = "observe" | "remember" | "updateRelationship" | "speak" | "requestAction";
+export type BehaviorPermissions = Record<BehaviorPermission, boolean>;
+export type BehaviorEventKind = "provocation" | "helpful" | "observation";
+export interface BehaviorPolicy {
+    general: BehaviorPermissions;
+    provocation: BehaviorPermissions;
+}
+export interface BehaviorGoal {
+    goalId: string;
+    objective: string;
+    priority: number;
+    enabled: boolean;
+}
+export interface ParameterDefinition {
+    parameterId: string;
+    label: string;
+    kind: "trait" | "state" | "relationship";
+    scope: "portable" | "world";
+    initial: number;
+    min: number;
+    max: number;
+    maxDelta: number;
+    decay?: {
+        perHour: number;
+        toward: number;
+    };
+}
+export interface BehaviorSettings {
+    policy: BehaviorPolicy;
+    goals: BehaviorGoal[];
+}
+export interface BehaviorOverride {
+    scope: {
+        kind: "npc" | "group" | "world";
+        id: string;
+    };
+    policy?: {
+        general?: Partial<BehaviorPermissions>;
+        provocation?: Partial<BehaviorPermissions>;
+    };
+    goals?: BehaviorGoal[];
+    initialValues?: Record<string, number>;
+}
+export interface BehaviorConfiguration {
+    version: "ifsoul-behavior/0.4.0";
+    revision: number;
+    parameters: ParameterDefinition[];
+    defaults: BehaviorSettings;
+    overrides: BehaviorOverride[];
+}
+/** Injected by trusted server composition; never accepted in configuration bodies. */
+export interface BehaviorOperatorPolicy {
+    canEditConfig: boolean;
+    lockedParameterIds: string[];
+    deniedPermissions: BehaviorPermission[];
+    lockedPolicy: boolean;
+    lockedGoals: boolean;
+}
+export interface BehaviorParameterValue {
+    npcId: string;
+    parameterId: string;
+    targetParticipantId?: string;
+    worldId?: string;
+    value: number;
+    confidence: number;
+    revision: number;
+    updatedAt: number;
+}
+export interface BehaviorChange {
+    changeId: string;
+    npcId: string;
+    parameterId: string;
+    targetParticipantId?: string;
+    worldId?: string;
+    before: number;
+    after: number;
+    confidence: number;
+    revision: number;
+    configRevision: number;
+    evidenceEventIds: string[];
+    reason: string;
+    kind: "evidence" | "decay";
+    recordedAt: number;
+}
+export interface BehaviorProposal {
+    proposalId: string;
+    npcId: string;
+    sessionId: string;
+    configRevision: number;
+    expectedStateRevision: number;
+    changes: {
+        parameterId: string;
+        targetParticipantId?: string;
+        delta: number;
+        confidence: number;
+        evidenceEventIds: string[];
+        reason: string;
+    }[];
+}
+export interface BehaviorObservation {
+    eventId: string;
+    npcId: string;
+    kind: BehaviorEventKind;
+    configRevision: number;
+    permissions: BehaviorPermissions;
+}
+export interface BehaviorState {
+    format: "ifsoul-behavior/0.4.0";
+    config: BehaviorConfiguration;
+    observations: BehaviorObservation[];
+    values: BehaviorParameterValue[];
+    history: BehaviorChange[];
+    proposals: {
+        proposal: BehaviorProposal;
+        revision: number;
+    }[];
+    stateRevisions: Record<string, number>;
+}
+export interface BehaviorInspection {
+    npcId: string;
+    sessionId: string;
+    configRevision: number;
+    stateRevision: number;
+    effective: BehaviorSettings & {
+        initialValues: Record<string, number>;
+    };
+    parameters: ParameterDefinition[];
+    values: BehaviorParameterValue[];
+    history: BehaviorChange[];
+}
+export interface BehaviorEditorSnapshot {
+    config: BehaviorConfiguration;
+    operator: BehaviorOperatorPolicy;
+    catalog: {
+        npcs: {
+            npcId: string;
+            label: string;
+        }[];
+        sessions: {
+            sessionId: string;
+            worldId: string;
+            npcIds: string[];
+        }[];
+        groups: {
+            groupId: string;
+            npcIds: string[];
+        }[];
+        worlds: string[];
+    };
+}

package/dist/packages/runtime/src/behavior-types.js

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

package/dist/packages/runtime/src/behavior.d.ts

@@ -0,0 +1,40 @@
+import type { ParticipantState, ParticipantStore, SessionAccess } from "./participants.js";
+import type { BehaviorConfiguration, BehaviorOperatorPolicy, BehaviorPermissions, BehaviorSettings, BehaviorInspection, BehaviorProposal, BehaviorEventKind, BehaviorEditorSnapshot } from "./behavior-types.js";
+export type * from "./behavior-types.js";
+export declare const DEFAULT_BEHAVIOR_OPERATOR: Readonly<BehaviorOperatorPolicy>;
+export interface BehaviorLimits {
+    parameters: number;
+    overrides: number;
+    values: number;
+    history: number;
+    observations: number;
+    proposals: number;
+    changesPerProposal: number;
+    evidencePerChange: number;
+}
+export declare const DEFAULT_BEHAVIOR_LIMITS: Readonly<BehaviorLimits>;
+export declare function defaultBehaviorConfiguration(): BehaviorConfiguration;
+/** World -> matching groups in lexicographic ID order -> NPC -> immutable operator denies. */
+export declare function effectiveBehavior(s: ParticipantState, access: SessionAccess, npcId: string, sessionId: string, operator?: BehaviorOperatorPolicy): BehaviorSettings & {
+    initialValues: Record<string, number>;
+};
+export declare function behaviorPermissions(s: ParticipantState, access: SessionAccess, npcId: string, sessionId: string, eventId?: string, operator?: BehaviorOperatorPolicy): BehaviorPermissions;
+export declare const behaviorRevision: (s: ParticipantState) => number;
+/** Previously unobserved/unremembered evidence never becomes implicit model context. */
+export declare function behaviorEvidenceVisible(s: ParticipantState, access: SessionAccess, npcId: string, sessionId: string, eventId: string, operator?: BehaviorOperatorPolicy): boolean;
+export declare function createBehaviorRuntime(store: ParticipantStore, options?: {
+    operator?: BehaviorOperatorPolicy;
+    limits?: Partial<BehaviorLimits>;
+    ceilings?: Partial<BehaviorLimits>;
+}): {
+    read(a: SessionAccess): BehaviorEditorSnapshot;
+    update(a: SessionAccess, expectedRevision: number, config: BehaviorConfiguration): BehaviorConfiguration;
+    adminInspect(a: SessionAccess, sessionId: string, npcId: string): BehaviorInspection;
+    inspect(a: SessionAccess, sessionId: string, npcId: string): BehaviorInspection;
+    observe(a: SessionAccess, sessionId: string, npcId: string, eventId: string, kind: BehaviorEventKind): {
+        observation: import("./behavior-types.js").BehaviorObservation;
+        fresh: boolean;
+    };
+    apply(a: SessionAccess, proposal: BehaviorProposal, nowMs: number): BehaviorInspection;
+    decay(a: SessionAccess, sessionId: string, npcId: string, nowMs: number): BehaviorInspection;
+};