@hviana/sema 0.2.9 → 0.4.0

package/dist/src/mind/mind.d.ts

@@ -44,6 +44,7 @@ export interface Conversation {
 import type { AttentionRead, MindContext, Recognition } from "./types.js";
 export type { AnchorRejectionReason, ClimbConsensusData, ConsensusAnchorTrace, ConsensusReachTrace, ConsensusRegionTrace, CrossRegionTier, JunctionVoteTrace, RegionOutcome, } from "./attention.js";
 export type { AncestorReach, SaturationReason, SaturationStop, } from "./types.js";
+import { type CostReport, Meter } from "../meter.js";
 export interface MindOptions {
     seed?: number;
     recallQueryK?: number;
@@ -58,6 +59,15 @@ export interface MindOptions {
     mechanisms?: import("./pipeline-mechanism.js").PipelineMechanism[];
     /** Factories that receive the {@link ExtensionHost} and return mechanisms. */
     mechanismFactories?: ((host: import("../extension.js").ExtensionHost) => import("./pipeline-mechanism.js").PipelineMechanism)[];
+    /** Measure the computational usage of every inference call — see
+     *  src/meter.ts.  Off by default and free when off (one null check per
+     *  store read); on, each `respond`/`respondTurn` leaves a {@link
+     *  Mind.lastCost} report behind.  Counters are deterministic, so two runs
+     *  of the same query on the same store are diffable; the millisecond
+     *  fields are not.  Profiling NEVER changes an answer — but note that
+     *  attaching a RATIONALE does (traced responses bypass the ctx memos,
+     *  AGENTS §2.11), so profile without a trace. */
+    profile?: boolean;
     /** Content canonicalizer applied to EVERY response (any modality) for
      *  equivalence-class resolution — see src/canon.ts.  Text entry points
      *  ({@link Mind.respondText}, {@link Mind.respondTurnText}) inject the
@@ -86,6 +96,19 @@ export declare class Mind implements MindContext {
      *  `false` to disable canonical resolution, or null to let each entry
      *  point decide (text entry points inject {@link textCanon}). */
     private _canonOpt;
+    /** The work accumulator for the inference call in flight — see
+     *  {@link MindContext.meter}.  Non-null only between beginResponse and
+     *  endResponse, and only when the Mind was constructed with
+     *  `{ profile: true }`. */
+    meter: Meter | null;
+    /** Whether {@link MindOptions.profile} was set. */
+    private _profile;
+    /** The computational-usage report of the LAST completed inference call, or
+     *  null when profiling is off (or nothing has been asked yet).  Overwritten
+     *  by every `respond`/`respondTurn`; copy it if you are aggregating.  See
+     *  {@link import("../meter.js").CostReport} and `sumReports`/`formatReport`
+     *  for battery-level aggregation. */
+    lastCost: CostReport | null;
     /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
     climbMemo: Map<string, Map<string, AttentionRead>> | null;
     /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
@@ -146,21 +169,49 @@ export declare class Mind implements MindContext {
     /** Perceive input into a content-defined tree.  Deterministic — identical
      *  bytes always produce an identical tree.  Public for ingest-cache. */
     perceive(input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null): Sema;
-    /** Open one response's transient state — the tracer and the per-response
-     *  memos.  Paired with {@link endResponse}; the ONE place this state is
-     *  created, so adding a memo cannot forget its reset. */
+    /** Open one response's transient state — the tracer, the per-response
+     *  memos, the work meter.  The ONE place this state is created, and it
+     *  serves BOTH entry points: `respond` takes fresh per-response memos,
+     *  `respondTurn` passes its conversation, whose memos persist across turns
+     *  (content-keyed, so the previous turn's results are found by this turn's
+     *  sub-span calls) and whose `resolvedSubtrees` makes foldTree O(suffix)
+     *  instead of O(context).  respondTurn used to inline its own copy of this
+     *  and of {@link endResponse}; the two drifted (a memo added to one was
+     *  silently absent from the other), so there is exactly one pair now. */
     private beginResponse;
+    /** Open (or leave closed) the response's work accumulator.  Separate from
+     *  {@link beginResponse} because {@link respondTurn} keeps its own
+     *  conversation-scoped lifecycle and must not create fresh per-response
+     *  memos — but it DOES meter, through this same pair. */
+    private _beginMeter;
+    /** Close the accumulator and publish its report.  Detaching from the store
+     *  matters: a Mind that shares a store with another Mind must not keep
+     *  charging that store's reads to a finished response. */
+    private _endMeter;
     /** The canonicalizer a response should carry: the Mind-level option when
      *  set (or none when explicitly disabled), else the entry point's own
      *  default — text entry points pass {@link textCanon}, binary ones null. */
     private _canonFor;
     /** Close one response's transient state — every per-response field, incl.
-     *  the edge guide/choices `think` sets mid-flight. */
+     *  the edge guide/choices `think` sets mid-flight, and the meter's report.
+     *
+     *  A conversation's memo MAPS were mutated in place, so `data.*` still
+     *  points at them and there is nothing to save back.  Clearing the Mind's
+     *  references is what matters: a concurrently-started `respond()` swaps its
+     *  own fresh maps into these pointers, and copying back from them here
+     *  would inject a foreign response's memos into the conversation. */
     private endResponse;
     /** Shared response core — the one path from bytes to voiced answer.
      *  `respond` calls this directly; `respondTurn` has its own path
      *  with conversation-persistent memos and incremental perception. */
     private _respondImpl;
+    /** The ONE path from query bytes to a voiced answer: ground (think), then
+     *  re-voice in the asker's words (articulate).  Both entry points run
+     *  exactly this — they differ only in the LIFECYCLE around it (fresh
+     *  per-response memos vs. a conversation's persistent ones) and in what
+     *  they do with the answer afterwards.  It must be called between
+     *  {@link beginResponse} and {@link endResponse}. */
+    private _groundAndVoice;
     respond(input: Input, inspectRationale?: InspectRationale): Promise<Response>;
     /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
      *  decoding — they are structural padding in text answers.  LOSSY for a
@@ -235,7 +286,10 @@ export declare class Mind implements MindContext {
      *  read-out direction of the same operation, without recall's grounding
      *  ladder.  If either side's acceptance rule changes, revisit the other. */
     express(idOrV: number | Vec): Promise<Uint8Array>;
-    ingest(input: Input | (Input | [Input, Input])[], second?: Input): Promise<(Sema & {
+    /** See {@link import("./learning.js").ingest} — `onDeposit`, when given,
+     *  reports each ingested item's deposited root node ids
+     *  ({@link DepositReport}); purely observational. */
+    ingest(input: Input | (Input | [Input, Input])[], second?: Input, onDeposit?: (report: import("./learning.js").DepositReport) => void): Promise<(Sema & {
         id: number;
     }) | undefined>;
     private extensionHost;

package/dist/src/mind/mind.js

@@ -29,6 +29,9 @@ import { aluToMechanism, defaultMechanisms, think } from "./pipeline.js";
 import { articulate } from "./articulation.js";
 import { ingest } from "./learning.js";
 import { rItem } from "./trace.js";
+// The work meter is exported from src/index.ts (via src/meter.ts) — the one
+// definition; the Mind only consumes it.
+import { Meter } from "../meter.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // THE MIND
 // ═══════════════════════════════════════════════════════════════════════════
@@ -53,6 +56,19 @@ export class Mind {
      *  `false` to disable canonical resolution, or null to let each entry
      *  point decide (text entry points inject {@link textCanon}). */
     _canonOpt = null;
+    /** The work accumulator for the inference call in flight — see
+     *  {@link MindContext.meter}.  Non-null only between beginResponse and
+     *  endResponse, and only when the Mind was constructed with
+     *  `{ profile: true }`. */
+    meter = null;
+    /** Whether {@link MindOptions.profile} was set. */
+    _profile = false;
+    /** The computational-usage report of the LAST completed inference call, or
+     *  null when profiling is off (or nothing has been asked yet).  Overwritten
+     *  by every `respond`/`respondTurn`; copy it if you are aggregating.  See
+     *  {@link import("../meter.js").CostReport} and `sumReports`/`formatReport`
+     *  for battery-level aggregation. */
+    lastCost = null;
     /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
     climbMemo = null;
     /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
@@ -120,8 +136,9 @@ export class Mind {
             this.store = storeArg;
         }
         else {
-            const { store: optsStore, mechanisms: userMechs, mechanismFactories: userFacts, canon: optsCanon, ...rest } = (optsOrCfg ?? {});
+            const { store: optsStore, mechanisms: userMechs, mechanismFactories: userFacts, canon: optsCanon, profile: optsProfile, ...rest } = (optsOrCfg ?? {});
             this._canonOpt = optsCanon ?? null;
+            this._profile = optsProfile === true;
             this.cfg = resolveConfig(rest);
             this.store = optsStore ?? new SQliteStore({
                 maxGroup: this.cfg.geometry.maxGroup,
@@ -180,16 +197,44 @@ export class Mind {
     perceive(input, leafAt, lookup) {
         return perceiveImpl(this, input, leafAt, lookup);
     }
-    /** Open one response's transient state — the tracer and the per-response
-     *  memos.  Paired with {@link endResponse}; the ONE place this state is
-     *  created, so adding a memo cannot forget its reset. */
-    beginResponse(inspectRationale, canon) {
+    /** Open one response's transient state — the tracer, the per-response
+     *  memos, the work meter.  The ONE place this state is created, and it
+     *  serves BOTH entry points: `respond` takes fresh per-response memos,
+     *  `respondTurn` passes its conversation, whose memos persist across turns
+     *  (content-keyed, so the previous turn's results are found by this turn's
+     *  sub-span calls) and whose `resolvedSubtrees` makes foldTree O(suffix)
+     *  instead of O(context).  respondTurn used to inline its own copy of this
+     *  and of {@link endResponse}; the two drifted (a memo added to one was
+     *  silently absent from the other), so there is exactly one pair now. */
+    beginResponse(inspectRationale, canon, conv) {
         this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
-        this.climbMemo = new Map();
-        this.recogniseMemo = new Map();
-        this.perceiveMemo = new Map();
+        this.climbMemo = conv ? conv.climbMemo : new Map();
+        this.recogniseMemo = conv ? conv.recogniseMemo : new Map();
+        this.perceiveMemo = conv ? conv.perceiveMemo : new Map();
+        this._resolvedSubtrees = conv ? conv.resolvedSubtrees : null;
         this.canon = canon ?? null;
         this.canonMemo = canon ? new Map() : null;
+        this._beginMeter();
+    }
+    /** Open (or leave closed) the response's work accumulator.  Separate from
+     *  {@link beginResponse} because {@link respondTurn} keeps its own
+     *  conversation-scoped lifecycle and must not create fresh per-response
+     *  memos — but it DOES meter, through this same pair. */
+    _beginMeter() {
+        if (!this._profile)
+            return;
+        this.meter = new Meter();
+        this.store.meter = this.meter;
+    }
+    /** Close the accumulator and publish its report.  Detaching from the store
+     *  matters: a Mind that shares a store with another Mind must not keep
+     *  charging that store's reads to a finished response. */
+    _endMeter(queryBytes) {
+        if (this.meter === null)
+            return;
+        this.lastCost = this.meter.report(queryBytes);
+        this.store.meter = null;
+        this.meter = null;
     }
     /** The canonicalizer a response should carry: the Mind-level option when
      *  set (or none when explicitly disabled), else the entry point's own
@@ -200,12 +245,20 @@ export class Mind {
         return this._canonOpt ?? entryDefault;
     }
     /** Close one response's transient state — every per-response field, incl.
-     *  the edge guide/choices `think` sets mid-flight. */
-    endResponse() {
+     *  the edge guide/choices `think` sets mid-flight, and the meter's report.
+     *
+     *  A conversation's memo MAPS were mutated in place, so `data.*` still
+     *  points at them and there is nothing to save back.  Clearing the Mind's
+     *  references is what matters: a concurrently-started `respond()` swaps its
+     *  own fresh maps into these pointers, and copying back from them here
+     *  would inject a foreign response's memos into the conversation. */
+    endResponse(queryBytes) {
+        this._endMeter(queryBytes);
         this.trace = null;
         this.climbMemo = null;
         this.recogniseMemo = null;
         this.perceiveMemo = null;
+        this._resolvedSubtrees = null;
         this.canon = null;
         this.canonMemo = null;
         this._edgeGuide = null;
@@ -217,26 +270,38 @@ export class Mind {
     async _respondImpl(queryBytes, inspectRationale, traceLabel = "respond", canon = null) {
         this.beginResponse(inspectRationale, canon);
         try {
-            const top = this.trace?.enter(traceLabel, [
-                rItem(queryBytes, "query"),
-            ]);
-            const thought = await think(this, queryBytes, this.mechanisms);
-            if (thought === null) {
-                top?.done([], "nothing to perceive or an empty store — no answer");
-                return { v: null, bytes: new Uint8Array(0) };
-            }
-            const voiced = await articulate(this, thought.bytes, queryBytes);
-            top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
-            return {
-                v: gistOf(this, voiced),
-                bytes: voiced,
-                provenance: thought.provenance,
-            };
+            return await this._groundAndVoice(queryBytes, traceLabel);
         }
         finally {
-            this.endResponse();
+            this.endResponse(queryBytes.length);
         }
     }
+    /** The ONE path from query bytes to a voiced answer: ground (think), then
+     *  re-voice in the asker's words (articulate).  Both entry points run
+     *  exactly this — they differ only in the LIFECYCLE around it (fresh
+     *  per-response memos vs. a conversation's persistent ones) and in what
+     *  they do with the answer afterwards.  It must be called between
+     *  {@link beginResponse} and {@link endResponse}. */
+    async _groundAndVoice(queryBytes, traceLabel) {
+        const top = this.trace?.enter(traceLabel, [rItem(queryBytes, "query")]);
+        const meter = this.meter;
+        const thought = meter
+            ? await meter.time("think", () => think(this, queryBytes, this.mechanisms))
+            : await think(this, queryBytes, this.mechanisms);
+        if (thought === null) {
+            top?.done([], "nothing to perceive or an empty store — no answer");
+            return { v: null, bytes: new Uint8Array(0) };
+        }
+        const voiced = meter
+            ? await meter.time("articulate", () => articulate(this, thought.bytes, queryBytes))
+            : await articulate(this, thought.bytes, queryBytes);
+        top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
+        return {
+            v: gistOf(this, voiced),
+            bytes: voiced,
+            provenance: thought.provenance,
+        };
+    }
     async respond(input, inspectRationale) {
         // A STRING input is text by nature: it carries the text equivalence even
         // through the generic entry point.  Raw bytes / grids carry only the
@@ -358,82 +423,36 @@ export class Mind {
             throw new Error(`Conversation ${conv.id} not found`);
         const turnBytes = inputBytes(this, turn);
         // Incremental perception — O(turn) instead of O(context).
-        const tree = this._growContext(data, turnBytes);
+        this._growContext(data, turnBytes);
         const newContext = data.bytes;
-        // Swap in the conversation's persistent state so the inference
-        // pipeline does not re-process the prefix from scratch.
-        //   perceiveMemo / recogniseMemo / climbMemo — content-keyed;
-        //     the prefix's results from the previous turn are found by
-        //     the current turn's sub-span calls.
-        //   _resolvedSubtrees — Sema-node-keyed; when the pyramid reuses
-        //     prefix subtrees (identical objects), foldTree returns their
-        //     ids immediately — O(suffix) instead of O(context).
-        this.perceiveMemo = data.perceiveMemo;
-        this.recogniseMemo = data.recogniseMemo;
-        this.climbMemo = data.climbMemo;
-        this._resolvedSubtrees = data.resolvedSubtrees;
-        this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
-        // A string turn is text by nature — carry the text equivalence, same as
+        // The conversation's persistent memos and subtree cache are swapped in
+        // by beginResponse (see there) — the SAME lifecycle respond() uses, so a
+        // memo added in one place can never be missing from the other.  A string
+        // turn is text by nature and carries the text equivalence, same as
         // respond() (see _canonFor).
-        this.canon = this._canonFor(typeof turn === "string" ? textCanon : null);
-        this.canonMemo = this.canon ? new Map() : null;
+        //
+        // No recognise-memo pre-seeding here: that used to be necessary because
+        // the flat/positional fold lost visibility into an earlier turn's own
+        // structure once later bytes shifted its position (foldTree no longer
+        // visited the turn's root node).  The STABLE-PREFIX fold (see {@link
+        // ConversationData}) makes every turn's subtree independent of what
+        // follows it by construction, so recognise() finds it correctly on its
+        // own, first-touch, exactly once per turn.
+        this.beginResponse(inspectRationale, this._canonFor(typeof turn === "string" ? textCanon : null), data);
         try {
-            // No recognise-memo pre-seeding here: that used to be necessary
-            // because the flat/positional fold lost visibility into an earlier
-            // turn's own structure once later bytes shifted its position
-            // (foldTree no longer visited the turn's root node).  The
-            // STABLE-PREFIX fold (see {@link ConversationData}) makes every
-            // turn's subtree independent of what follows it by construction, so
-            // recognise() finds it correctly on its own, first-touch, exactly
-            // once per turn — no workaround needed, and none pre-empting
-            // recognise()'s own memo with a partial result.
-            const top = this.trace?.enter("respondTurn", [
-                rItem(newContext, "query"),
-            ]);
-            const thought = await think(this, newContext, this.mechanisms);
-            if (thought === null) {
-                top?.done([], "nothing to perceive or an empty store — no answer");
-                return {
-                    response: { v: null, bytes: new Uint8Array(0) },
-                    state: this.conversationState(conv),
-                };
-            }
-            const voiced = await articulate(this, thought.bytes, newContext);
-            top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
+            const response = await this._groundAndVoice(newContext, "respondTurn");
             // The REPLY joins the accumulated context the same way a turn does
             // ({@link addTurn}): raw byte append plus a boundary offset — never a
             // separator.  A conversation's context is the full exchange, exactly
             // the cumulative continuous shape multi-turn training deposits, so a
             // later turn can refer to what was ANSWERED ("which of those two…"),
             // not only to what was asked.
-            if (voiced.length > 0)
-                this.addTurn(conv, voiced);
-            return {
-                response: {
-                    v: gistOf(this, voiced),
-                    bytes: voiced,
-                    provenance: thought.provenance,
-                },
-                state: this.conversationState(conv),
-            };
+            if (response.bytes.length > 0)
+                this.addTurn(conv, response.bytes);
+            return { response, state: this.conversationState(conv) };
         }
         finally {
-            // No save-back: the conversation's memo MAPS were mutated in place —
-            // `data.*` still points at them.  Re-assigning from the Mind-level
-            // pointers here was a no-op in the single-flight case and, under a
-            // concurrently-started respond() (which swaps its own fresh maps into
-            // those pointers), would inject a FOREIGN response's memos into this
-            // conversation.  Clear Mind references — non-conversation respond()
-            // calls get fresh per-response memos.
-            this.trace = null;
-            this.perceiveMemo = null;
-            this.recogniseMemo = null;
-            this.climbMemo = null;
-            this.canon = null;
-            this.canonMemo = null;
-            this._resolvedSubtrees = null;
-            this._edgeGuide = null;
-            this._edgeChoice.clear();
+            this.endResponse(newContext.length);
         }
     }
     /** Text view of {@link respondTurn}.  See {@link respondText} for the
@@ -464,8 +483,11 @@ export class Mind {
         return new Uint8Array(0);
     }
     // ── Learning ─────────────────────────────────────────────────────────────
-    async ingest(input, second) {
-        return ingest(this, input, second);
+    /** See {@link import("./learning.js").ingest} — `onDeposit`, when given,
+     *  reports each ingested item's deposited root node ids
+     *  ({@link DepositReport}); purely observational. */
+    async ingest(input, second, onDeposit) {
+        return ingest(this, input, second, onDeposit);
     }
     // ── Extension Surface ────────────────────────────────────────────────────
     extensionHost() {

package/dist/src/mind/pipeline-mechanism.d.ts

@@ -37,9 +37,21 @@ export declare class Precomputed {
      *  any future identity-based mechanism reads the same cache. */
     windowsOf(anchor: number): Map<number, number>;
     /** Shared memo for {@link reachOf} (structural-IDF reads): a window's
-     *  ancestor reach is a pure function of the read-only store, so one
-     *  response-scoped memo serves every mechanism that prices commonality. */
-    readonly reachMemo: Map<number, AncestorReach>;
+     *  ancestor reach is a pure function of the read-only store, so one memo
+     *  serves every mechanism that prices commonality — AND the consensus
+     *  climb, which is the largest consumer and used to build its own.  The
+     *  ONE definition of its lifetime lives in traverse.ts
+     *  ({@link sharedReachMemo}): response-scoped for respond(),
+     *  conversation-scoped across turns, always cold under a trace. */
+    private _reach?;
+    get reachMemo(): Map<number, AncestorReach>;
+    /** Charge a lazily-shared analysis to its OWN phase rather than to the
+     *  mechanism that happened to first-touch it.  Without this the profile
+     *  reads as "cast.floor costs 2 s" when what actually cost 2 s is the
+     *  consensus climb — which cast merely paid for on everyone's behalf, and
+     *  which every later consumer then got free.  Attribution must follow the
+     *  work, not the caller. */
+    private shared;
     private _attention?;
     /** The full consensus climb (roots + ranked anchors) — the query-level
      *  evidence CAST, confluence, extraction, recall's scaffolding tier, and
@@ -109,6 +121,24 @@ export interface MechanismResult {
     /** Override the mechanism's default provenance for this result.
      *  When absent, the pipeline uses `mech.provenance`. */
     provenance?: string;
+    /** This grounding is a COMPLETE trained answer — post-grounding must not
+     *  extend it.  Declared by the mechanism about its own result, exactly like
+     *  `accounted`/`used`/`unexplained`; the decider honours the property and
+     *  never asks which mechanism set it, so the market stays uniform.
+     *
+     *  Set it only when the answer is a stored form's OWN continuation reached
+     *  through an identity claim about the query — i.e. the query IS some
+     *  trained context, so its continuation is the whole read-out and a further
+     *  multi-hop pivot would chain PAST the fact that produced the answer.
+     *  That is the same reasoning `reason`'s echo guard already applies to a
+     *  query that resolves exactly (see reasoning.ts); this carries the claim
+     *  for the mechanisms that establish the identity by another route.
+     *
+     *  Observed without it: the correct "What is the process of
+     *  photosynthesis?" grounding was pivoted forward four times, out of the
+     *  fact that answered it and into an unrelated "Hello! How can I assist you
+     *  today?" conversational turn. */
+    complete?: boolean;
 }
 export interface PipelineMechanism {
     /** Stable identifier for trace/debug. */