@ifsoul/core 0.4.0 → 0.6.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.6.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/memory/src/port.d.ts

@@ -28,6 +28,35 @@ export interface RecallQuery {
     maxBytes: number;
     publicOnly?: boolean;
 }
+export interface MemoryScanQuery {
+    characterId: string;
+    /** Trusted owner-visible identities. Every participant on a non-public row must be listed. */
+    visibleParticipantIds: string[];
+    /** Exact full-text phrase over retained canonical event documents. */
+    text?: string;
+    /** Skip the candidate count when iterating an anchored projection. */
+    includeTotal?: boolean;
+    after?: number;
+    through?: number;
+    anchor?: string;
+    /** A reset excludes earlier entries in this environment, including after cursor creation. */
+    reset?: {
+        environmentId: string;
+        eventType: string;
+    };
+    limit: number;
+}
+export interface MemoryScanPage {
+    entries: {
+        sequence: number;
+        event: MemoryEvent;
+    }[];
+    through: number;
+    anchor: string;
+    next?: number;
+    /** Authorized event count within the current search anchor. */
+    total?: number;
+}
 /** Trusted local storage port; do not expose unrestricted methods to controllers or hosts. */
 export interface MemoryPort {
     putCharacter(character: CharacterInstance): Result<CharacterInstance>;
@@ -42,6 +71,8 @@ export interface MemoryPort {
         events: MemoryEvent[];
     }): Result<void>;
     recall(query: RecallQuery): Result<MemoryEvent[]>;
+    /** Trusted owner inspection only. Bounds retained events; exchange journals are excluded. */
+    scan?(query: MemoryScanQuery): Result<MemoryScanPage>;
     /** Trusted owner-only atomic retention. Exact source IDs must still exist in the
      * nominated character/environment/scope. Replacements validate before pruning.
      * Optional for older adapters; callers must reject unsupported retention. */

package/dist/packages/memory/src/sql.d.ts

@@ -10,4 +10,6 @@ export interface SQLDriver {
 }
 export declare const MEMORY_SCHEMA = "CREATE TABLE IF NOT EXISTS characters (id TEXT PRIMARY KEY, document TEXT NOT NULL);\nCREATE TABLE IF NOT EXISTS exchanges (id TEXT PRIMARY KEY, character_id TEXT NOT NULL REFERENCES characters(id), document TEXT NOT NULL);\nCREATE TABLE IF NOT EXISTS events (sequence INTEGER PRIMARY KEY, id TEXT UNIQUE NOT NULL, character_id TEXT NOT NULL REFERENCES characters(id), environment_id TEXT NOT NULL, document TEXT NOT NULL);\nCREATE INDEX IF NOT EXISTS event_scope ON events(character_id, environment_id, sequence);";
 export declare function validScope(scope: Scope): boolean;
-export declare function createSQLMemory(db: SQLDriver, closeOwner?: () => void): MemoryPort;
+export declare function createSQLMemory(db: SQLDriver, closeOwner?: () => void, options?: {
+    indexedSearch?: boolean;
+}): MemoryPort;

package/dist/packages/memory/src/sql.js

@@ -19,7 +19,7 @@ export function validScope(scope) {
                 ? scope.participantIds.length === 1
                 : scope.participantIds.length > 0));
 }
-export function createSQLMemory(db, closeOwner = () => { }) {
+export function createSQLMemory(db, closeOwner = () => { }, options = {}) {
     let closed = false;
     const guarded = (action) => {
         if (closed)
@@ -268,6 +268,110 @@ export function createSQLMemory(db, closeOwner = () => { }) {
             }
             return success(selected.reverse());
         }),
+        scan: (query) => guarded(() => {
+            const after = query.after ?? 0;
+            if (!query.visibleParticipantIds.length ||
+                query.visibleParticipantIds.length > 32 ||
+                !Number.isSafeInteger(query.limit) ||
+                query.limit < 1 ||
+                query.limit > 128 ||
+                !Number.isSafeInteger(after) ||
+                after < 0 ||
+                (query.through !== undefined &&
+                    (!Number.isSafeInteger(query.through) || query.through < after)))
+                return failure("budget-exceeded", "Memory scan bounds are invalid.");
+            const queryText = query.text?.trim() ?? "";
+            if (queryText.length > 120 || queryText.includes("\0"))
+                return failure("invalid-document", "Invalid memory search text.");
+            if (queryText && !options.indexedSearch)
+                return failure("unsupported", "This store does not support full-text memory search.");
+            const visibility = `(json_extract(document,'$.scope.audience')='public' OR (
+          json_extract(document,'$.scope.audience') IN ('private', 'participants')
+          AND json_array_length(document,'$.scope.participantIds') > 0
+          AND NOT EXISTS (
+            SELECT 1 FROM json_each(events.document,'$.scope.participantIds') AS recipient
+            WHERE recipient.value NOT IN (SELECT value FROM json_each(?))
+          )
+        ))`;
+            const audience = JSON.stringify(query.visibleParticipantIds);
+            const anchor = query.through === undefined
+                ? db
+                    .prepare(`SELECT sequence, id FROM events WHERE character_id=? AND ${visibility} ORDER BY sequence DESC LIMIT 1`)
+                    .get(query.characterId, audience)
+                : db
+                    .prepare(`SELECT sequence, id FROM events WHERE character_id=? AND sequence=? AND ${visibility}`)
+                    .get(query.characterId, query.through, audience);
+            const through = Number(anchor?.sequence ?? 0);
+            const anchorId = String(anchor?.id ?? "");
+            if (query.through !== undefined &&
+                (through !== query.through || anchorId !== query.anchor))
+                return failure("stale-context", "Retained memory changed. Start the search again.");
+            const reset = query.reset;
+            const resetAt = reset
+                ? Number(db
+                    .prepare(`SELECT sequence FROM events
+              WHERE character_id=? AND environment_id=?
+                AND json_extract(document,'$.eventType')=? AND ${visibility}
+              ORDER BY sequence DESC LIMIT 1`)
+                    .get(query.characterId, reset.environmentId, reset.eventType, audience)?.sequence ?? 0)
+                : 0;
+            const textFilter = queryText
+                ? "AND sequence IN (SELECT rowid FROM event_search_v1 WHERE event_search_v1 MATCH ?)"
+                : "";
+            const textArgs = queryText
+                ? [`"${queryText.replaceAll('"', '""')}"`]
+                : [];
+            const visibleRange = `character_id=? AND sequence<=?
+          AND (?=0 OR environment_id<>? OR sequence>?)
+          AND ${visibility} ${textFilter}`;
+            const rangeArgs = [
+                query.characterId,
+                through,
+                resetAt,
+                reset?.environmentId ?? "",
+                resetAt,
+                audience,
+                ...textArgs,
+            ];
+            const total = query.includeTotal === false
+                ? undefined
+                : Number(db
+                    .prepare(`SELECT count(*) AS total FROM events WHERE ${visibleRange}`)
+                    .get(...rangeArgs)?.total ?? 0);
+            const rows = db
+                .prepare(`WITH page AS (
+            SELECT sequence, length(CAST(document AS BLOB)) AS bytes
+            FROM events WHERE sequence>? AND ${visibleRange}
+            ORDER BY sequence LIMIT ?
+          ), sized AS (
+            SELECT sequence, sum(bytes) OVER (ORDER BY sequence) AS total,
+              row_number() OVER (ORDER BY sequence) AS position FROM page
+          )
+          SELECT sized.sequence, CASE WHEN position=1 OR total<=512000 AND position<=?
+            THEN events.document END AS document
+          FROM sized JOIN events ON events.sequence=sized.sequence ORDER BY sized.sequence`)
+                .all(after, ...rangeArgs, query.limit + 1, query.limit);
+            const entries = [];
+            let next;
+            for (const row of rows) {
+                const sequence = Number(row.sequence);
+                if (typeof row.document !== "string") {
+                    next = entries.at(-1)?.sequence;
+                    break;
+                }
+                entries.push({
+                    sequence,
+                    event: stored(row.document, "memory-event"),
+                });
+            }
+            return success({
+                entries,
+                through,
+                anchor: anchorId,
+                total,
+                ...(next === undefined ? {} : { next }),
+            });
+        }),
         close: () => {
             try {
                 closeOwner();

package/dist/packages/memory/src/sqlite-search.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseSync } from "node:sqlite";
+/** External-content index, with canonical event documents as the sole source. */
+export declare function initializeEventSearch(database: DatabaseSync): boolean;

package/dist/packages/memory/src/sqlite-search.js

@@ -0,0 +1,44 @@
+/** External-content index, with canonical event documents as the sole source. */
+export function initializeEventSearch(database) {
+    database.exec("BEGIN IMMEDIATE");
+    try {
+        const existing = database
+            .prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='event_search_v1'")
+            .get();
+        database.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS event_search_v1 USING fts5(
+        document, content='events', content_rowid='sequence', tokenize='unicode61'
+      );
+      CREATE TABLE IF NOT EXISTS event_search_versions (version INTEGER PRIMARY KEY);
+      CREATE TRIGGER IF NOT EXISTS event_search_v1_insert AFTER INSERT ON events BEGIN
+        INSERT INTO event_search_v1(rowid, document) VALUES (new.sequence, new.document);
+      END;
+      CREATE TRIGGER IF NOT EXISTS event_search_v1_delete AFTER DELETE ON events BEGIN
+        INSERT INTO event_search_v1(event_search_v1, rowid, document)
+        VALUES ('delete', old.sequence, old.document);
+      END;
+      CREATE TRIGGER IF NOT EXISTS event_search_v1_update AFTER UPDATE ON events BEGIN
+        INSERT INTO event_search_v1(event_search_v1, rowid, document)
+        VALUES ('delete', old.sequence, old.document);
+        INSERT INTO event_search_v1(rowid, document) VALUES (new.sequence, new.document);
+      END;
+    `);
+        if (!existing ||
+            !database
+                .prepare("SELECT 1 FROM event_search_versions WHERE version=1")
+                .get()) {
+            database.exec(`
+        INSERT INTO event_search_v1(event_search_v1) VALUES ('rebuild');
+        INSERT OR REPLACE INTO event_search_versions(version) VALUES (1);
+      `);
+        }
+        database.exec("COMMIT");
+        return true;
+    }
+    catch (error) {
+        database.exec("ROLLBACK");
+        if (error instanceof Error && error.message === "no such module: fts5")
+            return false;
+        throw error;
+    }
+}

package/dist/packages/memory/src/sqlite.js

@@ -3,6 +3,7 @@ import { closeSync, existsSync, mkdirSync, openSync, realpathSync, statSync, unl
 import { basename, dirname, join, resolve } from "node:path";
 import { failure, success } from "./port.js";
 import { createSQLMemory, MEMORY_SCHEMA } from "./sql.js";
+import { initializeEventSearch } from "./sqlite-search.js";
 export { validScope } from "./sql.js";
 /** Opens one locally owned SQLite writer. Never removes an existing ownership lock. */
 export function openSQLiteMemory(filename) {
@@ -49,6 +50,8 @@ export function openSQLiteMemory(filename) {
             chmodSync(path, 0o600);
         database.exec("PRAGMA foreign_keys=ON; PRAGMA journal_mode=DELETE;");
         database.exec(MEMORY_SCHEMA);
+        database.exec("CREATE INDEX IF NOT EXISTS event_owner_sequence ON events(character_id, sequence)");
+        const indexedSearch = initializeEventSearch(database);
         const db = database;
         let closed = false;
         return success(createSQLMemory({
@@ -71,7 +74,7 @@ export function openSQLiteMemory(filename) {
                 closed = true;
             }
             release();
-        }));
+        }, { indexedSearch }));
     }
     catch {
         let connectionClosed = true;

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.6.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.6.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;
+};