@hviana/sema 0.3.0 → 0.4.1

package/AGENTS.md

@@ -145,6 +145,14 @@ matcher or projection, add it **to the shared family** with a derived gate
 aligning, edge-following to a fixpoint, predecessor-picking, or fan-out capping
 is reintroducing duplication that was deliberately removed.
 
+A shared analysis must not live inside a mechanism. If `pipeline-mechanism.ts`
+(the shared contract and `Precomputed`) or a post-grounding stage has to import
+_out of_ `mechanisms/`, the dependency is inverted and the market's decoupling
+(2.6) is broken — deleting that mechanism would break the shared container. The
+span-shape family (`isSpanShaped` / `containsSpan` / `skillExemplar`) was
+exactly this and now lives in `match.ts`, where its two consumers can reach it
+without knowing extraction exists.
+
 Related single-definition contracts (define once, import everywhere):
 
 - `canonical.ts` — the write/read contract for canonical segmentation
@@ -327,7 +335,49 @@ _Follow it:_ when your code can degrade, emit a counter or trace step. And mind
 the classic trap: **empty bytes are truthy** — `Uint8Array(0)` passes
 `if (answer)`; always test `.length`.
 
-### 2.14 Comment style
+### 2.14 Measured, not guessed — the work meter
+
+`src/meter.ts` is the one computational-usage accounting surface: a `Meter`
+counts the WORK one inference call performs at every layer (store reads by kind
+and by VOLUME, ANN queries and vectors scanned, perceptions, recognitions,
+climbs and ancestor visits, alignment cells, chart pops, mechanism floors/runs)
+and times named PHASES. Off by default and free when off;
+`new Mind({ profile:
+true })` attaches one per response and leaves a
+`CostReport` on `mind.lastCost`. `bench/profile-inference.mjs` is the reference
+harness.
+
+It is the profiling counterpart of the rationale — the rationale says why an
+answer was chosen, the meter says what it cost. Four contracts:
+
+1. **Never read by inference.** A counter that reached a decision would end
+   determinism (2.1). Write-only from the engine's side.
+2. **Counts are the product; times are the hint.** Counters are deterministic,
+   so two runs are diffable and a work regression is visible without a
+   stopwatch. Only `elapsedMs` and the phase millisecond totals are not.
+3. **Phases nest, and carry their own counter deltas.** `think` ⊃ `<mech>.run` ⊃
+   `substitutionBridge` ⊃ `recall.exhaustiveResonate`. Inclusive, never summed —
+   but each phase reports the work done inside it (`PhaseCost.counters`), which
+   is what makes "which phase did those byte reads?" answerable at all.
+4. **Count a logical operation once.** A recursive read (`bytesPrefix`
+   descending a branch) is charged at the public entry point only — the private
+   `_prefix` body is uncharged. Counting the recursion made one read of an
+   N-byte branch report as N reads, so the counter measured tree size instead of
+   read requests.
+5. **Shared analyses are charged to themselves.** `attention`, `weave`,
+   `spanShaped` and `substitutionBridge` bill their own phase, not the mechanism
+   that happened to first-touch them — otherwise the profile blames whoever paid
+   on everyone's behalf (it once read "cast.floor costs 2.9 s" when 2.7 s of
+   that was the consensus climb).
+
+_Follow it:_ a new layer that wants to be visible bumps a field in `meter.ts` —
+never a private counter. (`danglingReads`/`compactFailures` in `store.ts` stay:
+those are session-lifetime HEALTH counters, not per-response work.) Add the
+counter to the report the same way, and remember the classic trap: **profile
+without a trace attached** — a trace bypasses the memos (2.11) and measures a
+different machine.
+
+### 2.15 Comment style
 
 Comments state _constraints and failure modes_ — "this guard exists because X
 breaks without it", often naming the test that pins the behaviour — never
@@ -360,6 +410,7 @@ story of the fix.
 | Learning / ingestion / training cache         | `src/mind/learning.ts`, `src/ingest-cache.ts`                          |
 | Post-grounding (reason, fuse, articulate)     | `src/mind/reasoning.ts`, `src/mind/articulation.ts`                    |
 | Rationale / trace                             | `src/mind/rationale.ts`, `src/mind/trace.ts`                           |
+| Computational-usage meter                     | `src/meter.ts` (harness: `bench/profile-inference.mjs`)                |
 | Extension host types                          | `src/extension.ts`                                                     |
 | Sublibraries (own READMEs, own tests)         | `src/derive/`, `src/alu/`, `src/rabitq-ivf/`                           |
 
@@ -427,6 +478,19 @@ recognition found, how the climb voted, which edges were followed
 (`disambiguate` steps carry the evidence). `recall-echo` means "nearest stored
 form, not a derived fact". Remember traced responses bypass memos (2.11).
 
+### Profile an answer
+
+```ts
+const mind = new Mind({ store, profile: true }); // no trace — see 2.14
+await mind.respondText(query);
+console.log(formatReport(mind.lastCost!)); // counters by layer + nested phases
+```
+
+`bench/profile-inference.mjs` runs a battery this way and prints per-query and
+aggregate reports; `sumReports` aggregates a run. Diff the COUNTERS between two
+runs to catch a work regression — they are deterministic; read the PHASES to see
+where the wall clock went.
+
 ### Train at scale
 
 Use `CachedIngest` (`ingest-cache.ts`) as a drop-in for `mind.ingest` — it
@@ -450,10 +514,12 @@ against the built `dist/` (`npm test`; one suite:
 - New behaviour ⇒ a test in the matching numbered suite, or a new numbered
   suite.
 - Many tests pin **contracts that look like implementation details** (the bridge
-  tier order, extraction's two span-shape readings, determinism, honest
-  silence). A "simplification" that fails an existing test is wrong until you
-  can argue the _test_ is wrong — several guards exist precisely because a
-  plausible simplification once failed a dozen suites.
+  tier order, the bridge's identity admission vs. its prefix trap and the
+  scaffolding reading behind it, the two span-shape readings (`match.ts`),
+  `MechanismResult.complete`, determinism, honest silence). A "simplification"
+  that fails an existing test is wrong until you can argue the _test_ is wrong —
+  several guards exist precisely because a plausible simplification once failed
+  a dozen suites.
 - Sublibraries test themselves (`src/{alu,derive,rabitq-ivf}/test/`) with zero
   Sema dependency. Keep it so.
 - Performance claims are tested (the rabitq-ivf benchmark asserts sub-linear

package/CONTRIBUTING.md

@@ -1,15 +1,97 @@
-# Contributing
+# Contributing to Sema
 
-By contributing to Sema, you agree that:
+Thank you for your interest in contributing to Sema.
 
-- you have the legal right to submit your contribution;
-- your contribution does not violate third-party rights;
-- your contribution will be licensed under the PolyForm Noncommercial License
-  1.0.0;
-- this project is source-available, not formally open source;
-- commercial use requires a separate paid license;
-- you will not submit secrets, credentials, private keys, or confidential data.
+Sema is source-available software distributed publicly under the PolyForm
+Noncommercial License 1.0.0. Commercial use requires a separate commercial
+license from the Sema licensor.
 
-All commits should be signed off:
+## Contributor representations
 
+By submitting a contribution to Sema, you represent that:
+
+- you created the contribution or otherwise have the legal right to submit it
+  under these terms;
+- the contribution does not knowingly violate any copyright, patent, trade
+  secret, contractual obligation, or other third-party right;
+- you have obtained any authorization required from your employer or another
+  rights holder;
+- you have clearly identified any third-party material included in the
+  contribution and provided its applicable license and copyright notices;
+- the contribution does not contain secrets, credentials, private keys,
+  confidential information, or unlawfully obtained material;
+- if the contribution was created with the assistance of an artificial
+  intelligence system, you have reviewed it and remain responsible for its
+  origin, legality, correctness, and compliance with these terms.
+
+## Contribution license grant
+
+You retain ownership of the copyright in your contribution.
+
+By intentionally submitting a contribution for inclusion in Sema, you grant
+Henrique Viana, as the author, copyright holder, and licensor of Sema, and his
+successors and assigns, a worldwide, perpetual, irrevocable, non-exclusive,
+royalty-free, transferable, and sublicensable license to:
+
+- use, reproduce, modify, adapt, and prepare derivative works from the
+  contribution;
+- combine the contribution with Sema or other materials;
+- publicly display, publicly perform, distribute, make available, host, and
+  otherwise exploit the contribution;
+- offer, license, and sublicense the contribution as part of Sema under the
+  PolyForm Noncommercial License 1.0.0;
+- offer, license, and sublicense the contribution as part of commercial,
+  proprietary, source-available, or other versions of Sema;
+- relicense the contribution as part of Sema under current or future licensing
+  terms.
+
+This license grant does not transfer ownership of your contribution to Henrique
+Viana. You remain free to use and license your original contribution
+independently, provided that doing so does not violate rights belonging to Sema
+or to third parties.
+
+## Patent license
+
+To the extent that you own or control patent claims necessarily infringed by
+your contribution, you grant Henrique Viana, his successors and assigns, and
+recipients of Sema a worldwide, perpetual, irrevocable, non-exclusive,
+royalty-free, transferable, and sublicensable patent license to make, use, sell,
+offer for sale, import, and otherwise exploit your contribution as part of Sema.
+
+This patent license terminates for any party that initiates patent litigation
+alleging that Sema or a contribution incorporated into Sema infringes a patent.
+
+## No obligation to accept contributions
+
+Submitting a contribution does not guarantee that it will be accepted, merged,
+published, maintained, or included in any public or commercial version of Sema.
+
+The project maintainer may modify, reject, remove, or replace an accepted
+contribution.
+
+## Developer Certificate of Origin
+
+All commits must include a Developer Certificate of Origin sign-off:
+
+```bash
 git commit -s
+```
+
+The sign-off must use your real name and an email address you are authorized to
+use:
+
+```text
+Signed-off-by: Your Name <your.email@example.com>
+```
+
+The sign-off certifies the origin and authorization of each commit. It does not
+replace the contribution license grant described in this document.
+
+## Acceptance
+
+By opening or submitting a pull request, patch, or other contribution intended
+for inclusion in Sema, you confirm that you have read and agree to these
+contribution terms.
+
+Contributions submitted on behalf of a company or another organization must be
+authorized by the applicable rights holder.

package/LICENSE.md

@@ -2,8 +2,8 @@
 
 <https://polyformproject.org/licenses/noncommercial/1.0.0>
 
-> Required Notice: Copyright Sema Authors — Henrique Viana, Marcelo Oliveira dos
-> Reis, Rogerio Nascimento (hv5088@gmail.com)
+> Required Notice: Copyright © Henrique Viana (author). Marcelo Oliveira dos
+> Reis and Rogerio Nascimento (supporters).
 
 ## Acceptance
 

package/dist/src/derive/src/deduction.d.ts

@@ -118,8 +118,19 @@ export interface Derivation<I> {
     /** Derivations of the rule's premises (empty for an axiom). */
     premises: Array<Derivation<I>>;
 }
+/** Optional search-effort read-out, filled in place while the search runs.
+ *  A plain structural record so the sublibrary stays firewalled (it imports
+ *  nothing from Sema, and Sema copies these into its own accounting).  Purely
+ *  observational: the search never reads it back. */
+export interface SearchStats {
+    /** Agenda entries popped, stale lazy-deletion entries included — the chart
+     *  work actually done. */
+    pops: number;
+    /** Agenda entries pushed by a successful relaxation. */
+    pushes: number;
+}
 /**
  * Find a lightest derivation of a goal item, or `null` if none exists.
  * `cost` on the returned root is the total derivation cost.
  */
-export declare function lightestDerivation<I>(system: DeductionSystem<I>): Derivation<I> | null;
+export declare function lightestDerivation<I>(system: DeductionSystem<I>, stats?: SearchStats): Derivation<I> | null;

package/dist/src/derive/src/deduction.js

@@ -43,7 +43,7 @@ import { MinHeap } from "./priority-queue.js";
  * Find a lightest derivation of a goal item, or `null` if none exists.
  * `cost` on the returned root is the total derivation cost.
  */
-export function lightestDerivation(system) {
+export function lightestDerivation(system, stats) {
     const g = new Map(); // best known cost per item
     const proof = new Map(); // producing rule per item
     const items = new Map(); // key → the item it stands for
@@ -82,6 +82,8 @@ export function lightestDerivation(system) {
             g.set(key, cost);
             proof.set(key, rule);
             items.set(key, item);
+            if (stats)
+                stats.pushes++;
             agenda.push(cost + h(item, key), { key, g: cost });
         }
     };
@@ -89,6 +91,8 @@ export function lightestDerivation(system) {
         relax(item, cost, null);
     while (agenda.size > 0) {
         const { value } = agenda.pop();
+        if (stats)
+            stats.pops++;
         const key = value.key;
         // Lazy deletion: an entry is stale if a cheaper derivation has since been
         // recorded for the same item.

package/dist/src/derive/src/index.d.ts

@@ -1,4 +1,5 @@
 export { lightestDerivation } from "./deduction.js";
+export type { SearchStats } from "./deduction.js";
 export type { DeductionSystem, Derivation, PooledConclusion, PooledContribution, Rule, } from "./deduction.js";
 export { coverSequence } from "./rewrite.js";
 export type { CandidateSpan, Cover } from "./rewrite.js";

package/dist/src/geometry.d.ts

@@ -105,6 +105,7 @@ export interface Grid {
     data: Uint8Array;
     dims?: number[];
 }
+export declare function contentBoundaries(space: Space, bytes: Uint8Array): number[];
 /** Find the longest prefix of `bytes` whose leaf-id signature matches a
  *  known branch via `lookup`.  Returns the byte-length of that prefix, or 0. */
 export declare function knownPrefixLength(bytes: Uint8Array, leafAt: (i: number) => number | null, lookup: (leafIds: number[]) => number | null): number;
@@ -129,9 +130,8 @@ export declare function bytesToTree(space: Space, alphabet: Alphabet, bytes: Uin
  *  grown stream whose boundary set EXTENDS a previous fold's reuses every
  *  matching segment's Folded unchanged (segments fold independently by
  *  construction, so reuse is bit-identical to refolding) and folds only the
- *  new right-edge segment — O(turn) per extension, the stable-prefix
- *  counterpart of {@link FoldPyramid}.  Purely a cache: the produced tree
- *  never depends on cache state. */
+ *  new right-edge segment — O(turn) per extension.  Purely a cache: the
+ *  produced tree never depends on cache state. */
 export interface StableFold {
     edges: number[];
     segs: Folded[];
@@ -170,33 +170,6 @@ export interface StructuralPart {
  *  concatenated byte string, and never interns or stores a new node: the
  *  result is an opaque, ungrounded Vec for an ANN probe only. */
 export declare function composeStructuralGist(space: Space, parts: readonly StructuralPart[]): Vec;
-/** The PLAIN fold's full level pyramid — every level's item list, bottom
- *  (leaves) to top (root).  Left-grouped folding is RADIX-ALIGNED: the item
- *  at level L, index i, covers exactly bytes [i·mg^L, (i+1)·mg^L) whenever
- *  it is a FULL block, and a full block folds bit-identically in ANY byte
- *  string that contains it at that offset.  So a string extended by a
- *  suffix (a conversation's accumulated context) reuses every full block of
- *  its prefix's pyramid and refolds only the right edge of each level —
- *  O(suffix + depth·mg) per extension instead of O(whole), with the
- *  produced tree BIT-IDENTICAL to a from-scratch plain fold (same nodes,
- *  same FP ops; reused subtrees are shared objects, and Sema nodes are
- *  never mutated).  Purely an implementation cache: structure and numerics
- *  never depend on whether a pyramid was available. */
-export interface FoldPyramid {
-    levels: Array<Array<{
-        tree: Sema;
-        len: number;
-    }>>;
-    bytes: number;
-}
-/** Plain bytes→tree (identical to capability-less {@link bytesToTree}) that
- *  also RETURNS its pyramid, reusing `prev` — the pyramid of a PROPER
- *  prefix of `bytes` (caller guarantees content match and
- *  prev.bytes < bytes.length). */
-export declare function bytesToTreePyramid(space: Space, alphabet: Alphabet, bytes: Uint8Array, prev?: FoldPyramid): {
-    tree: Sema;
-    pyramid: FoldPyramid;
-};
 export declare function hilbertBytes(grid: Grid): Uint8Array;
 export declare function gridToTree(space: Space, alphabet: Alphabet, grid: Grid): Sema;
 export declare function stackGrids(frames: Grid[]): Grid;