mirror/rea
1
0
Fork 0
mirror of https://github.com/morluto/rea synced 2026-10-27 22:45:19 -04:00
Code Issues Packages Projects Releases Wiki Activity

perf(experiment): separate discovery summaries from full contracts

Browse Source 
Return explicit method intents in reference indexes while preserving all full contracts, topic matching and complete MCP catalogs. Separate provider-free contracts from session admission and defer native loading until open.

Validate 82 related tests, exact SDK/MCP full-contract parity, real zlib CLI/SDK reads and native/inspection cleanup retries. Freeze the unchanged two-level question for an order-reversed real-model repeat.

Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
This commit is contained in:
N0zoM1z0
2026-10-16 18:57:16 +00:00
parent 3e4c0d8b59
commit 65b701df54
13 changed files with 357 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
experiments/atomic-codemode/README.md
+10 -2
View File
@@ -28,6 +28,12 @@ now pass: Code Mode reduces cumulative input but increases uncached input, time,
CPU and memory in this pair. Correct facts support both calling strategies;
the query-cache improvement is separate from those mixed whole-task costs.
The [discovery-summary study](discovery-summary-study.md) addresses repeated
metadata from that pair. The complete method index now uses owned intent
summaries; all full contracts and advertised tools remain available. Contracts
and session admission have separate owners, with native loading deferred to open.
Its repeat uses the same frozen control question and retains the earlier results.
The [exact-value query study](value-query-study.md) adds location-to-value and
value-to-operand-use queries, including inputs/constants without defining operations.
Real stripped OpenSSH checks preserve all 250 SSA versions / 369 occurrences at
@@ -49,8 +55,10 @@ Three boundaries own the implementation:
- `provider.mjs`, `native-ir.mjs`: existing REA native target/process owners and parsed Kuna
string/reference/SSA facts, retained sources, freshness and cleanup.
- `api.mjs`: named, validated fact/relationship contracts and session admission.
SDK callers, CLI scripts and both MCP adapters use these same methods.
- `api.mjs`: named, validated fact/relationship contracts and their intent summaries.
`session.mjs` owns shared admission and lease/file cleanup, loading the native
provider only on open. SDK callers, CLI scripts and both MCP adapters use these
same contracts and application owner.
- `executor.mjs`, `server.mjs`, `cli.mjs`: bounded JavaScript composition and
presentation. No analysis is reimplemented in the execution environment.
experiments/atomic-codemode/api.mjs
+88 -129
View File
@@ -1,11 +1,7 @@
// One named contract registry shared by SDK, CLI, direct MCP and Code Mode.
import { z } from "zod";
import { KunaFactOwner } from "./provider.mjs";
import { FactFailure } from "./fact-error.mjs";
import { MAX_BYTE_BATCH_BYTES } from "./limits.mjs";
import { createReference } from "./reference.mjs";
import { ArtifactResourceScope } from "../../dist/artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../../dist/artifacts/ArtifactReader.js";
const hex = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/u);
const snapshot = z.string().startsWith("snap_");
@@ -49,7 +45,8 @@ const fields = z
]),
)
.optional();
const definition = (description, input, method, example) => ({
const definition = ({ summary, description }, input, method, example) => ({
summary,
description,
input: z.strictObject(input),
method,
@@ -87,7 +84,12 @@ const relationInput = z.discriminatedUnion("kind", [
]);
export const methods = {
switches: definition(
"Inspect recovered indirect branches and their independent native jump-table metadata, without returning all case rows. Selector is the current recovered BRANCHIND input, which may be normalized rather than the machine jump address. Native consumed mask and signed rendering hint are not complete runtime/signedness proofs. Null tables/defaults stay unknown. The native model default out-edge is separate from any machine out-of-range guard destination. Use relations kind:cases for selected raw table rows, labels and their native mapping to recovered edges; row/edge ordinals are not case values. Available even when the full graph is unavailable if this independent facet was captured.",
{
summary:
"Select recovered switches/table metadata; fetch cases separately. Native defaults may differ from machine guards.",
description:
"Inspect recovered indirect branches and their independent native jump-table metadata, without returning all case rows. Selector is the current recovered BRANCHIND input, which may be normalized rather than the machine jump address. Native consumed mask and signed rendering hint are not complete runtime/signedness proofs. Null tables/defaults stay unknown. The native model default out-edge is separate from any machine out-of-range guard destination. Use relations kind:cases for selected raw table rows, labels and their native mapping to recovered edges; row/edge ordinals are not case values. Available even when the full graph is unavailable if this independent facet was captured.",
},
{
snapshot,
ids: z.array(z.string()).max(128).optional(),
@@ -99,7 +101,12 @@ export const methods = {
'await rea.switches({snapshot:s,origin_addresses:["0x1000"]})',
),
functions: definition(
"Search retained native callable entries by literal name/alias, exact name, or entry addresses. Names can match several entries, including PLT/import stubs and implementations; preserve all matches and select by address. A name does not establish runtime symbol binding.",
{
summary:
"Select callable entries and aliases, preserving ambiguous names; reported sizes are bounds, not assured extents.",
description:
"Search retained native callable entries by literal name/alias, exact name, or entry addresses. Names can match several entries, including PLT/import stubs and implementations; preserve all matches and select by address. A name does not establish runtime symbol binding.",
},
{
query: z.string().default(""),
exact: z.boolean().default(false),
@@ -112,13 +119,23 @@ export const methods = {
'await rea.functions({query:"format_error",exact:true})',
),
strings: definition(
"Search retained string inventory by literal text. Paging does not establish artifact completeness.",
{
summary:
"Search retained encoded strings by literal text; discovery and reference attribution remain unknown.",
description:
"Search retained string inventory by literal text. Paging does not establish artifact completeness.",
},
{ query: z.string(), ...page },
"strings",
'await rea.strings({query:"incorrect header check"})',
),
references: definition(
"Batch incoming or outgoing lifted-code references without decompilation. Address scope selects exact target (incoming) or source instruction (outgoing); function scope selects outgoing native owning-function references and requires an entry address. Unknown function applicability stays unknown. Kind filtering is pushed to the native query; source rows, endpoints and Evidence identity remain. Recovered IR calls are a separate representation and may omit machine calls. Interior string references require a separate extent query.",
{
summary:
"Read incoming exact-address or outgoing address/function xrefs with occurrence identity and ownership coverage.",
description:
"Batch incoming or outgoing lifted-code references without decompilation. Address scope selects exact target (incoming) or source instruction (outgoing); function scope selects outgoing native owning-function references and requires an entry address. Unknown function applicability stays unknown. Kind filtering is pushed to the native query; source rows, endpoints and Evidence identity remain. Recovered IR calls are a separate representation and may omit machine calls. Interior string references require a separate extent query.",
},
{
addresses: z.array(hex).min(1).max(16),
direction: z.enum(["incoming", "outgoing"]).default("incoming"),
@@ -136,13 +153,23 @@ export const methods = {
'await rea.references({addresses:["0x2000"]})',
),
snapshot: definition(
"Analyze an explicit function entry once; return a retained capture handle, facets and coverage. Reuses the source within this target lease. Code, recovered calls and values remain independently available when full recovered IR exceeds capacity. A bounded call-rooted operation/definition projection may also be available; inspect facets.operations and coverage before reads. CFG queries still require the complete recovered graph. Available calls include compact by_opcode counts of known/unknown targets over the whole retained call facet; no paging is needed for these counts. Selected calls and complete Evidence remain readable.",
{
summary:
"Capture one function's analysis; return a snapshot, retained Evidence, facet availability and scoped counts.",
description:
"Analyze an explicit function entry once; return a retained capture handle, facets and coverage. Reuses the source within this target lease. Code, recovered calls and values remain independently available when full recovered IR exceeds capacity. A bounded call-rooted operation/definition projection may also be available; inspect facets.operations and coverage before reads. CFG queries still require the complete recovered graph. Available calls include compact by_opcode counts of known/unknown targets over the whole retained call facet; no paging is needed for these counts. Selected calls and complete Evidence remain readable.",
},
{ entry: hex },
"snapshot",
'await rea.snapshot({entry:"0x1000"})',
),
bytes: definition(
"Read selected native loaded-image bytes without instruction decoding. Batch up to 16 exact virtual-address windows and 64 KiB total selected bytes; hex uses twice that space before provenance. Short reads remain partial. These are not live process memory or an original-file-offset mapping. Global code discovery is not performed.",
{
summary:
"Read batched static loaded-image byte ranges with source identity and per-window partial outcomes.",
description:
"Read selected native loaded-image bytes without instruction decoding. Batch up to 16 exact virtual-address windows and 64 KiB total selected bytes; hex uses twice that space before provenance. Short reads remain partial. These are not live process memory or an original-file-offset mapping. Global code discovery is not performed.",
},
{
windows: z.array(byteWindow).min(1).max(16),
},
@@ -150,7 +177,12 @@ export const methods = {
'await rea.bytes({windows:[{address:"0x2000",length:32}]})',
),
instructions: definition(
"Batch selected machine instruction windows. Read exact bytes and native disassembly to verify actual control transfers; optimized recovered CFG edges can bypass machine blocks. Address+size with the artifact context identifies the byte range. A caller-selected decode start does not prove execution/alignment.",
{
summary:
"Decode selected static machine-byte windows, distinct from optimized IR edges and runtime execution.",
description:
"Batch selected machine instruction windows. Read exact bytes and native disassembly to verify actual control transfers; optimized recovered CFG edges can bypass machine blocks. Address+size with the artifact context identifies the byte range. A caller-selected decode start does not prove execution/alignment.",
},
{
windows: z
.array(
@@ -169,7 +201,12 @@ export const methods = {
'await rea.instructions({windows:[{address:"0x1000",count:8}],fields:["bytes","text"]})',
),
operations: definition(
"Select SSA operations by IDs, source instruction origins, block IDs, constant literal or kind. Native default rows are compact summaries: opcode/kind/output and input/definition/constant counts; request detailed fields explicitly or page input slots via relations kind:operands. Filters intersect; identities and native is_dead are retained. Availability may be a complete recovered graph or a bounded call-rooted projection; inspect coverage before inferring absence. A literal match is not object identity. origin_addresses selects optimized recovered IR origins; use instructions for actual machine control transfers.",
{
summary:
"Select snapshot-local IR operations by identity, origin, constant or kind, with native/projection scope.",
description:
"Select SSA operations by IDs, source instruction origins, block IDs, constant literal or kind. Native default rows are compact summaries: opcode/kind/output and input/definition/constant counts; request detailed fields explicitly or page input slots via relations kind:operands. Filters intersect; identities and native is_dead are retained. Availability may be a complete recovered graph or a bounded call-rooted projection; inspect coverage before inferring absence. A literal match is not object identity. origin_addresses selects optimized recovered IR origins; use instructions for actual machine control transfers.",
},
{
snapshot,
ids: z.array(z.string()).max(128).optional(),
@@ -184,6 +221,8 @@ export const methods = {
'await rea.operations({snapshot:s,constant:"0x2000",fields:["statement"]})',
),
relations: {
summary:
"Read typed SSA operands/def-use, CFG/controllers or switch cases by identities; preserve unknown/partial scope.",
description:
"Read native operand occurrences, operation definitions/uses, value_uses or case rows. value_uses takes value-ID seeds and returns exact operation/input-slot occurrences, including function inputs and constants without defining operations; null definition stays explicit, not a missing use. Uses cover retained operations, not runtime or memory aliases. Other data-flow/case seeds are operation IDs; incoming/outgoing CFG edges or derived controllers for block IDs. Native CFG/controller reads deduplicate seeds and report unretained_seeds; an unknown block is not a retained block with no relations. Incoming/outgoing rows keep caller seed then native edge order; controllers keep native controller/edge then postdominator order. cases pages one relation per case/out-edge, with a stable case_id; an unmapped case has one explicit unknown-edge row. total counts relations, not table rows. cases filters optional case_values (native labels tagged value) and case_indices (original row ordinals); both filters intersect and paging spans deduplicated seeds in caller order. Rows preserve missing/no-label status, original recovered target, and separate recovered edges. Partial/unavailable tables and unmapped rows are explicit; no runtime feasibility claim. operands pages every selected input slot, including constants, function inputs and null slots; input_indices optionally selects slots in caller order. Identity is snapshot + operation + input_index; value_id/definition and exact phi predecessor/edge bindings remain separate. Out-of-range slots of retained operations are absent; unretained_seeds remain unknown. A bounded call-rooted projection supports operands/definitions/uses but no CFG; uses cover retained selected operations only. Diagnostic SSA lacks native operands and has partial CFG/printed occurrences. controllers requires a complete recovered graph and concerns finite paths to recovered exits, not runtime feasibility.",
input: relationInput,
@@ -192,7 +231,12 @@ export const methods = {
'await rea.relations({snapshot:s,kind:"operands",seeds:[op.id],input_indices:[0,2]})',
},
values: definition(
"Read native SSA values by IDs or exact locations [{space,offset,size_bytes}], with width required. Locations match retained metadata, including const/unique spaces, not pointee contents, aliases or live memory. Filters intersect; IDs retain caller order, otherwise locations retain caller order and values retain native order per location. Empty IDs/locations select none. Null-space values cannot resolve a location and stay explicit in location_coverage; unretained_locations means no known retained coordinate match, not absent machine storage. Scope may be a full graph, bounded call-rooted definition projection, or call-boundary values only; is_input filters retained operand/output values, not an original source signature. Offset is an address-space offset, not a computed arbitrary-width value. Width, constants, function inputs, annotation status and defining operation are separate facts. Requires the pinned native exporter.",
{
summary:
"Select SSA values by ID or exact space/offset/width; keep versions, inputs and constants distinct, without alias inference.",
description:
"Read native SSA values by IDs or exact locations [{space,offset,size_bytes}], with width required. Locations match retained metadata, including const/unique spaces, not pointee contents, aliases or live memory. Filters intersect; IDs retain caller order, otherwise locations retain caller order and values retain native order per location. Empty IDs/locations select none. Null-space values cannot resolve a location and stay explicit in location_coverage; unretained_locations means no known retained coordinate match, not absent machine storage. Scope may be a full graph, bounded call-rooted definition projection, or call-boundary values only; is_input filters retained operand/output values, not an original source signature. Offset is an address-space offset, not a computed arbitrary-width value. Width, constants, function inputs, annotation status and defining operation are separate facts. Requires the pinned native exporter.",
},
{
snapshot,
ids: z.array(z.string()).max(128).optional(),
@@ -218,7 +262,12 @@ export const methods = {
"await rea.values({snapshot:s,ids:op.inputs.map(i=>i.value_id).filter(Boolean)})",
),
calls: definition(
"Select structured recovered call sites and argument bindings. Target comes from native call specifications, never the fspec annotation offset or display text. Each argument separates its SSA value from its passing storage. Calls and their boundary values survive full graph capacity failure. target_value_id retains input zero independently of target resolution; it may be an fspec annotation or an unresolved indirect target value. A null output describes this recovered operation, not proof of a void source signature. Input slots are not original source parameter ordinals; missing storage and indirect/runtime targets remain unknown. To investigate across functions, snapshot the selected callee and select values with is_input:true, comparing exact space/offset/width. Requires the pinned native exporter.",
{
summary:
"Read recovered calls, target knowledge, arguments and passing storage; signatures and runtime binding remain uncertain.",
description:
"Select structured recovered call sites and argument bindings. Target comes from native call specifications, never the fspec annotation offset or display text. Each argument separates its SSA value from its passing storage. Calls and their boundary values survive full graph capacity failure. target_value_id retains input zero independently of target resolution; it may be an fspec annotation or an unresolved indirect target value. A null output describes this recovered operation, not proof of a void source signature. Input slots are not original source parameter ordinals; missing storage and indirect/runtime targets remain unknown. To investigate across functions, snapshot the selected callee and select values with is_input:true, comparing exact space/offset/width. Requires the pinned native exporter.",
},
{
snapshot,
ids: z.array(z.string()).max(128).optional(),
@@ -243,7 +292,12 @@ export const methods = {
'await rea.calls({snapshot:s,origin_addresses:["0x1100"]})',
),
blocks: definition(
"Read native recovered blocks by stable snapshot-local ID, with ordered predecessors, successor edges and member operation IDs. origin_start describes optimized IR provenance, not a machine block extent. Requires an available native recovered IR graph. Runtime successors remain unknown.",
{
summary:
"Select recovered CFG blocks and edges; origin addresses are provenance, not machine block extents.",
description:
"Read native recovered blocks by stable snapshot-local ID, with ordered predecessors, successor edges and member operation IDs. origin_start describes optimized IR provenance, not a machine block extent. Requires an available native recovered IR graph. Runtime successors remain unknown.",
},
{
snapshot,
ids: z.array(z.number().int().nonnegative()).max(128).optional(),
@@ -258,7 +312,12 @@ export const methods = {
"await rea.blocks({snapshot:s,ids:[op.block]})",
),
slice: definition(
"Compose a bounded backward definition traversal from explicit operation IDs. Native default operation rows are compact summaries; request detailed fields or use paged operand relations for wide nodes. Available over a complete recovered graph or bounded call-rooted projection. Missing defining bodies retain frontier reasons; complete use sets and CFG are unavailable for a projection. Default load/phi cutoffs keep boundaries visible; choose stop_kinds:[] to traverse beyond them. Complete reachability and memory aliases remain unknown.",
{
summary:
"Trace bounded backward definitions with explicit LOAD/PHI/frontier cutoffs; memory aliases remain unknown.",
description:
"Compose a bounded backward definition traversal from explicit operation IDs. Native default operation rows are compact summaries; request detailed fields or use paged operand relations for wide nodes. Available over a complete recovered graph or bounded call-rooted projection. Missing defining bodies retain frontier reasons; complete use sets and CFG are unavailable for a projection. Default load/phi cutoffs keep boundaries visible; choose stop_kinds:[] to traverse beyond them. Complete reachability and memory aliases remain unknown.",
},
{
snapshot,
seeds: z.array(z.string()).min(1).max(64),
@@ -271,7 +330,12 @@ export const methods = {
'await rea.slice({snapshot:s,seeds:callIds,stop_kinds:["load"],fields:["opcode","inputs","output","constants"]})',
),
code: definition(
"Read reconstructed code from the same retained function capture, even when its graph facet is unavailable. offset is zero-based. A large limit reads the complete code inside Code Mode for local filtering. The bridge byte budget bounds the result. No additional decompilation.",
{
summary:
"Read selected lines of retained reconstructed code, including when graph capture is unavailable.",
description:
"Read reconstructed code from the same retained function capture, even when its graph facet is unavailable. offset is zero-based. A large limit reads the complete code inside Code Mode for local filtering. The bridge byte budget bounds the result. No additional decompilation.",
},
{
snapshot,
offset: page.offset,
@@ -281,7 +345,12 @@ export const methods = {
"await rea.code({snapshot:s,offset:100,limit:64})",
),
evidence: definition(
"Read complete retained native source in UTF-16-code-unit pages by evidence_id; no reanalysis. component:source preserves exact original wire JSON. component:recovered_ir reads the decoded graph source, including lossless compressed graphs; source hash remains the original capture and view has its own hash/byte count. This is source inspection, not a claim that malformed graph facts are valid. Available until close_binary.",
{
summary:
"Page complete retained source or decoded graph Evidence with source/view identities and freshness checks.",
description:
"Read complete retained native source in UTF-16-code-unit pages by evidence_id; no reanalysis. component:source preserves exact original wire JSON. component:recovered_ir reads the decoded graph source, including lossless compressed graphs; source hash remains the original capture and view has its own hash/byte count. This is source inspection, not a claim that malformed graph facts are valid. Available until close_binary.",
},
{
evidence_id: z.string().startsWith("ev_"),
component: z.enum(["source", "recovered_ir"]).default("source"),
@@ -332,115 +401,5 @@ methods.references.input = methods.references.input.superRefine(
});
},
);
export class AtomicSession {
#owner;
#tail = Promise.resolve();
#files = new ArtifactResourceScope();
constructor(factory = KunaFactOwner.open) {
this.factory = factory;
}
#admit(work) {
const pending = this.#tail.then(work, work);
this.#tail = pending.catch(() => {});
return pending;
}
get context() {
return this.#owner?.context ?? null;
}
abort() {
this.#owner?.cancel();
}
async #releaseFiles() {
try {
await this.#files.retryCleanup();
} catch (cause) {
const cleanup = ArtifactReaderFailure.cleanupObservation(
cause,
"Target session files",
);
throw new FactFailure("cleanup_incomplete", cleanup.reason, {
resources: cleanup.resources,
});
}
}
open(path) {
return this.#admit(async () => {
await this.#releaseFiles();
if (this.#owner) await this.#owner.close();
this.#owner = undefined;
this.#owner = await this.factory(path, {
fileResources: this.#files,
});
return {
ok: true,
context: this.context,
methods: Object.keys(methods),
evidence_lifetime: "current target lease",
};
});
}
close() {
return this.#admit(async () => {
if (this.#owner) await this.#owner.close();
await this.#releaseFiles();
this.#owner = undefined;
return { ok: true, closed: true };
});
}
call(
name,
input,
signal = new AbortController().signal,
lease = this.context?.lease,
) {
return this.#admit(async () => {
try {
if (signal.aborted)
throw new FactFailure(
"cancelled",
"Request was cancelled before admission",
);
if (!this.#owner)
throw new FactFailure(
"no_target",
"Call open_binary before analysis",
);
if (lease !== this.context.lease)
throw new FactFailure(
"stale_context",
"Target lease changed; do not join facts across leases",
);
if (!Object.hasOwn(methods, name))
throw new FactFailure(
"unknown_method",
`Unknown API method: ${name}`,
);
const contract = methods[name];
const parsed = contract.input.parse(input);
const data = await this.#owner[contract.method](parsed, signal);
if (signal.aborted)
throw new FactFailure(
"cancelled",
"Request was cancelled after observations were collected",
{ partial_observation: data },
);
return { ok: true, context: this.context, data };
} catch (error) {
return {
ok: false,
context: this.context,
error: {
code:
error instanceof z.ZodError
? "invalid_input"
: (error.code ?? "analysis_failed"),
message: error.message,
details: error.details ?? {},
},
};
}
});
}
}
export const reference = createReference(methods);
experiments/atomic-codemode/api.test.mjs
+2 -1
View File
@@ -1,7 +1,8 @@
import assert from "node:assert/strict";
import test from "node:test";
import Ajv2020 from "ajv/dist/2020.js";
import { AtomicSession, methods, reference } from "./api.mjs";
import { methods, reference } from "./api.mjs";
import { AtomicSession } from "./session.mjs";
const factory = () => {
let sequence = 0;
experiments/atomic-codemode/byte-facts.test.mjs
+1 -1
View File
@@ -1,7 +1,7 @@
import test from "node:test";
import assert from "node:assert/strict";
import { parseByteFacts } from "./byte-facts.mjs";
import { AtomicSession } from "./api.mjs";
import { AtomicSession } from "./session.mjs";
const make = () => ({
binary: "/input",
experiments/atomic-codemode/cli.mjs
+1 -1
View File
@@ -1,5 +1,5 @@
import { readFile } from "node:fs/promises";
import { AtomicSession } from "./api.mjs";
import { AtomicSession } from "./session.mjs";
import { executeJavaScript } from "./executor.mjs";
const [binary, script] = process.argv.slice(2);
experiments/atomic-codemode/discovery-summary-study.md
+86
View File
@@ -0,0 +1,86 @@
# Intent discovery without duplicated full contracts
The [two-level control pair](control-query-study.md) exposed a concrete metadata
cost. Code Mode first received a 9,890-byte method index, then 26,614 bytes of
selected contracts; the index already repeated substantial full descriptions.
Its uncached input exceeded direct's despite lower cumulative input. Metadata
bytes alone cannot explain that token difference: selected contracts, returned
facts and analysis choices also differed.
The shared registry now owns an explicit intent summary beside each full
method description. `reference(view:"index")` returns those summaries and every
matching method/name, without schemas or return contracts. It labels the result
as intent discovery, not complete semantics or live availability. Full contracts
remain on demand, including an explicit all-contracts request. Topic matching
still searches the full descriptions, so a detail omitted from a summary remains
searchable. No automatic sentence cutting, schema truncation or catalog filtering
is introduced. Caller selection/order and unmatched queries remain explicit.
The definition helper takes named summary/description metadata. `api.mjs` owns
contracts; `session.mjs` owns shared application admission and file/lease cleanup.
The default session factory imports the native provider only on open. All known
consumers now import `AtomicSession` from `session.mjs`; no compatibility wrapper
or second analysis implementation remains. CLI, SDK and both MCP adapters share
that owner. This changes metadata/loading, not native arguments, analysis caching
or retained-fact semantics.
## Actual contract and runtime checks
The complete SDK reference object is deeply equal to the saved before object:
all fifteen input schemas, full descriptions, return contracts, examples, limits
and notes match. Both actual MCP lanes preserve their selected full contracts
exactly. Every advertised schema compiles against Draft 2020-12; named handlers
match their contract identities. Actual catalogs still contain all eighteen
direct tools or four Code Mode tools. Topic/all/named selection, unknown queries,
caller order and timeout rejection/recovery pass.
| Actual MCP lane | Previous index bytes | Intent index bytes | Full-contract bytes, unchanged |
| --------------- | -------------------: | -----------------: | -----------------------------: |
| Code Mode | 9,890 | 2,849 | 31,804 |
| Direct | 9,920 | 2,879 | 30,116 |
Those are serialized JSON bytes, not model tokens. No token improvement follows
from that table alone. The all-contract size difference between lanes is their
existing naming/examples/execution presentation, not missing methods.
The related 82 tests pass after the module split. Real zlib SDK reads preserve
immutable cached strings/aliases and the complete source digest. The real CLI
composes function/string reads through the moved application owner. SDK cleanup
and replacement retry pass on SSH. Both MCP adapters retain and retry failed
engine-inspection descriptors and native-close owners. The faults are injected,
not observed OS/engine failures; native reads and successful cleanup use real
providers. Lint reports no warnings and formatting passes.
| Executed scope | Family wall s | Family CPU s | Kernel peak MiB |
| ----------------------------------------------- | ------------: | -----------: | --------------: |
| Before actual metadata verification, both lanes | 2.032 | 1.869 | 141.3 |
| Final actual metadata verification, both lanes | 1.831 | 1.592 | 130.0 |
| Final related 82 tests | 3.948 | 3.788 | 82.9 |
| Real zlib SDK | 1.528 | 1.297 | 124.6 |
| Real zlib CLI | 1.629 | 1.365 | 122.1 |
| SDK cleanup/replacement retry | 1.731 | 1.551 | 120.4 |
| Engine descriptor retry, Code Mode | 1.932 | 1.717 | 199.1 |
| Engine descriptor retry, direct | 1.831 | 1.645 | 191.4 |
| Native close retry, Code Mode | 1.832 | 1.610 | 187.8 |
| Native close retry, direct | 1.730 | 1.566 | 181.4 |
All run with one CPU, 4 GiB hard / 3 GiB early-stop memory, OOM/kill 0 and verified
payload cleanup. Kernel family peaks include charged file cache, not RSS. An
intermediate metadata check costs 1.731 wall / 1.503 CPU seconds and 129.5 MiB;
the preliminary 82-test run before module separation costs 19.536 / 13.950
seconds and 90.9 MiB. These are implementation/check stages with uncontrolled
host/JIT/cache conditions, not a causal analysis-speed benchmark. Raw receipts
remain local as `discovery-summary-*` under `.cache/atomic-codemode/`.
## Real-model repeat protocol
Reuse the unchanged [question and oracle](controller-oracle.md), frozen at
`8d13c67e7`, and its same pinned SQLite artifact and `a9ca8a8a...` engine. The
interface revision is a separate stratum; preserve both earlier completed answers
and all costs. Freeze runtime/HEAD before running, with the same complete tool
manifests, model/client/settings and common discovery/envelope/stopping/wait
guidance. Reverse the prior order: direct first, Code Mode second. Use fresh
isolated leases/private caches; OS/model caches and host contention remain
uncontrolled. Review complete answers and paths before comparing whole-task
usage, CPU and family memory. Module loading and model choices also change, so
the result cannot isolate a pure byte-count effect.
experiments/atomic-codemode/reference.mjs
+5 -2
View File
@@ -114,7 +114,10 @@ export const createReference =
const catalog = selected.keys.map((method) => ({
method,
name: labels[method],
description: methods[method].description,
description:
view === "index"
? methods[method].summary
: methods[method].description,
}));
const coverage = {
declared_methods: Object.keys(methods).length,
@@ -128,7 +131,7 @@ export const createReference =
coverage,
unmatched_queries: selected.unmatched,
notes: [
"Static declared methods, not live provider availability. Request exact displayed names with view:contracts for schemas; inspect snapshot facets for runtime coverage.",
"Intent summaries of static declared methods, not full contracts or live availability. Request exact displayed names with view:contracts for schemas and semantics; inspect snapshot facets for runtime coverage.",
],
};
return {
experiments/atomic-codemode/reference.test.mjs
+18 -2
View File
@@ -7,6 +7,8 @@ import { createReference } from "./reference.mjs";
test("reference index discovers named methods without constructing unrequested schemas", () => {
const registry = {
sample: {
summary:
"Discover a declared capability; inspect its full contract before use.",
description: "Declared capability; live coverage is unknown.",
get input() {
throw new Error("Schema was not requested");
@@ -22,7 +24,7 @@ test("reference index discovers named methods without constructing unrequested s
{
method: "sample",
name: "facts_sample",
description: registry.sample.description,
description: registry.sample.summary,
},
]);
assert.equal(index.coverage.view, "index");
@@ -41,13 +43,19 @@ test("reference index discovers named methods without constructing unrequested s
);
assert.ok(
all.methods.every(
(m) => !Object.hasOwn(m, "input_schema") && !Object.hasOwn(m, "returns"),
(m) =>
m.description === methods[m.method].summary &&
typeof m.description === "string" &&
m.description.length > 0 &&
!Object.hasOwn(m, "input_schema") &&
!Object.hasOwn(m, "returns"),
),
);
assert.ok(
Buffer.byteLength(JSON.stringify(all)) <
Buffer.byteLength(JSON.stringify(reference())),
);
assert.ok(all.notes.some((note) => note.includes("not full contracts")));
});
test("named reference lists preserve caller order and exact schemas across presentations", () => {
@@ -101,6 +109,14 @@ test("topic/all reference selection and shared schema ownership remain explicit"
assert.ok(
reference("memory aliases").methods.some((m) => m.method === "slice"),
);
assert.deepEqual(
reference("memory aliases", { view: "index" }).methods.map((m) => m.method),
reference("memory aliases").methods.map((m) => m.method),
);
for (const entry of reference().methods) {
assert.equal(entry.description, methods[entry.method].description);
assert.equal(methods[entry.method].method, entry.method);
}
const before = reference("snapshot").methods[0];
assert.throws(() => {
before.input_schema.properties.entry.type = "number";
experiments/atomic-codemode/server.mjs
+3 -2
View File
@@ -2,7 +2,8 @@
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
import { AtomicSession, methods, reference } from "./api.mjs";
import { methods, reference } from "./api.mjs";
import { AtomicSession } from "./session.mjs";
import { executeJavaScript } from "./executor.mjs";
import { referenceInput } from "./reference.mjs";
import { EXECUTION_LIMITS } from "./limits.mjs";
@@ -84,7 +85,7 @@ const createServer = () => {
);
register(
"reference",
"Discover fact methods with view:index and an empty query: returns names and descriptions without schemas. Then request only needed full contracts with view:contracts and exact displayed names or canonical IDs separated by spaces/commas. One topic query searches descriptions; empty query with view:contracts returns all contracts. These are static declared methods, not live provider availability.",
"Discover fact methods with view:index and an empty query: returns names and short intent summaries without schemas. Then request only needed full contracts and semantics with view:contracts and exact displayed names or canonical IDs separated by spaces/commas. One topic query searches full descriptions; empty query with view:contracts returns all contracts. These are static declared methods, not live provider availability.",
referenceInput,
(input) =>
reference(input.query, {
experiments/atomic-codemode/session.mjs
+122
View File
@@ -0,0 +1,122 @@
// Shared application admission and lease/file ownership; contracts stay provider-free.
import { z } from "zod";
import { methods } from "./api.mjs";
import { FactFailure } from "./fact-error.mjs";
import { ArtifactResourceScope } from "../../dist/artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../../dist/artifacts/ArtifactReader.js";
const openNativeOwner = async (path, options) => {
const { KunaFactOwner } = await import("./provider.mjs");
return KunaFactOwner.open(path, options);
};
export class AtomicSession {
#owner;
#tail = Promise.resolve();
#files = new ArtifactResourceScope();
constructor(factory = openNativeOwner) {
this.factory = factory;
}
#admit(work) {
const pending = this.#tail.then(work, work);
this.#tail = pending.catch(() => {});
return pending;
}
get context() {
return this.#owner?.context ?? null;
}
abort() {
this.#owner?.cancel();
}
async #releaseFiles() {
try {
await this.#files.retryCleanup();
} catch (cause) {
const cleanup = ArtifactReaderFailure.cleanupObservation(
cause,
"Target session files",
);
throw new FactFailure("cleanup_incomplete", cleanup.reason, {
resources: cleanup.resources,
});
}
}
open(path) {
return this.#admit(async () => {
await this.#releaseFiles();
if (this.#owner) await this.#owner.close();
this.#owner = undefined;
this.#owner = await this.factory(path, {
fileResources: this.#files,
});
return {
ok: true,
context: this.context,
methods: Object.keys(methods),
evidence_lifetime: "current target lease",
};
});
}
close() {
return this.#admit(async () => {
if (this.#owner) await this.#owner.close();
await this.#releaseFiles();
this.#owner = undefined;
return { ok: true, closed: true };
});
}
call(
name,
input,
signal = new AbortController().signal,
lease = this.context?.lease,
) {
return this.#admit(async () => {
try {
if (signal.aborted)
throw new FactFailure(
"cancelled",
"Request was cancelled before admission",
);
if (!this.#owner)
throw new FactFailure(
"no_target",
"Call open_binary before analysis",
);
if (lease !== this.context.lease)
throw new FactFailure(
"stale_context",
"Target lease changed; do not join facts across leases",
);
if (!Object.hasOwn(methods, name))
throw new FactFailure(
"unknown_method",
`Unknown API method: ${name}`,
);
const contract = methods[name];
const parsed = contract.input.parse(input);
const data = await this.#owner[contract.method](parsed, signal);
if (signal.aborted)
throw new FactFailure(
"cancelled",
"Request was cancelled after observations were collected",
{ partial_observation: data },
);
return { ok: true, context: this.context, data };
} catch (error) {
return {
ok: false,
context: this.context,
error: {
code:
error instanceof z.ZodError
? "invalid_input"
: (error.code ?? "analysis_failed"),
message: error.message,
details: error.details ?? {},
},
};
}
});
}
}
experiments/atomic-codemode/verify-cleanup.mjs
+1 -1
View File
@@ -2,7 +2,7 @@
// The failure is simulated; native reads and the successful retry use real owners.
import assert from "node:assert/strict";
import { stat, writeFile } from "node:fs/promises";
import { AtomicSession } from "./api.mjs";
import { AtomicSession } from "./session.mjs";
import { KunaFactOwner } from "./provider.mjs";
import { KunaTargetCommands } from "../../dist/kuna/KunaTargetCommands.js";
import { ProviderCleanupError } from "../../dist/domain/providerCleanupError.js";
experiments/atomic-codemode/verify-discovery.mjs
+19 -2
View File
@@ -6,6 +6,7 @@ import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import Ajv2020 from "ajv/dist/2020.js";
import { EXECUTION_LIMITS } from "./limits.mjs";
import { methods } from "./api.mjs";
import {
createVerifierRun,
completeVerifierRun,
@@ -37,6 +38,17 @@ for (const direct of [false, true]) {
try {
await client.connect(transport);
const catalog = await client.listTools();
assert.deepEqual(
catalog.tools.map((tool) => tool.name).sort(),
[
"open_binary",
"close_binary",
"reference",
...(direct
? Object.keys(methods).map((name) => `facts_${name}`)
: ["execute_javascript"]),
].sort(),
);
const prefix = direct ? "facts_" : "rea.";
const ids = [
"switches",
@@ -183,7 +195,11 @@ for (const direct of [false, true]) {
assert.deepEqual(missing.unmatched_queries, ["unknown"]);
const all = await call("");
assert.equal(all.methods.length, 15);
for (const method of all.methods) ajv.compile(method.input_schema);
for (const method of all.methods) {
ajv.compile(method.input_schema);
assert.equal(method.description, methods[method.method].description);
assert.equal(methods[method.method].method, method.method);
}
const index = await call("", "index");
assert.equal(index.coverage.view, "index");
assert.deepEqual(
@@ -205,7 +221,7 @@ for (const direct of [false, true]) {
all.methods.map((m) => ({
method: m.method,
name: m.name,
description: m.description,
description: methods[m.method].summary,
})),
);
assert.ok(
@@ -215,6 +231,7 @@ for (const direct of [false, true]) {
assert.ok(JSON.stringify(selected).length < JSON.stringify(all).length);
results.push({
direct,
catalog_tools: catalog.tools.map((tool) => tool.name),
selected,
all_reference_bytes: Buffer.byteLength(JSON.stringify(all)),
index_bytes: Buffer.byteLength(JSON.stringify(index)),
experiments/atomic-codemode/verify-sdk.mjs
+1 -1
View File
@@ -2,7 +2,7 @@
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { writeFile } from "node:fs/promises";
import { AtomicSession } from "./api.mjs";
import { AtomicSession } from "./session.mjs";
const [binary, output] = process.argv.slice(2);
assert.ok(binary && output, "Usage: verify-sdk.mjs ZLIB OUTPUT");