Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@ jobs:

- name: Run tests
run: npm run test

- name: Run discovery experiments and controls
run: npm run test:experiments

- name: Build packages
run: npm run build
Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,12 @@ console.log(result.issues.length); // 3

## Examples

- **[Algorithm search for FX and Beetle](./docs/advanced/algorithm-search.md)** — search scan,
early-exit and indexing algorithms against independent correctness checks and withheld cases.

- **[Experimental program discovery](./docs/advanced/program-discovery.md)** — inspectable programs,
parameterized abstraction learning, bounded search, and reproducible transfer and GPU scheduling experiments.

- **[Coding Agent](./examples/coding-agent/)** - Full-featured coding assistant
- **[Research Agent](./examples/research-agent/)** - Advanced research and analysis

Expand Down Expand Up @@ -323,4 +329,4 @@ npm test

## Support

- 📖 [Documentation](./docs/)
- 📖 [Documentation](./docs/)
169 changes: 169 additions & 0 deletions docs/advanced/algorithm-search.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
# Algorithm search for FX and Beetle

This extension searches executable **control flow**: loops, scan direction,
conditions, early exits and indexes. It complements the numeric program and
abstraction experiments; it does not require an LLM or coding agent to run.

```sh
npm ci
npm run algorithm:search -- --target fx-memory
npm run algorithm:search -- --target beetle-routes
npm run algorithm:search -- --target all --out ./algorithm-results
```

The output directory receives a report and a runnable `.algorithm.json` winner
for each accepted target. A rejected final result sets a nonzero CLI exit code
and writes `null` to the algorithm file, replacing any stale export. The report
retains the failed candidate. No production file, route, authorization, deployment or active
policy is changed. Search results must be inspected before integration.

## Included targets

| Target | Correctness source | Structures searched |
| --- | --- | --- |
| `fx-memory` | The actual `getMemory` implementation in `src/memory.ts` | Predicate ordering, full forward scan, guarded reverse scan with early exit, plus intentionally incorrect variants |
| `beetle-routes` | A synthetic reference model of nearest-address / first-converse selection over a fixed batch | Repeated scans, bucket indexes, precomputed reader indexes, preference and address-order variants |

### FX memory filtering

Each input contains JSON-normalized memory `entries` and a `filter` with explicit
nullable `type`, `since`, `search` and `limit` fields. Entry timestamps are finite
millisecond numbers. The oracle reconstructs Dates, calls the real FX
`getMemory`, and normalizes the complete resulting entries back to JSON.

The candidate must preserve case-insensitive search, type and date filtering,
array order and every entry field. Cases cover empty results, missing/zero limits,
negative and fractional limits, large limits and nonchronological entry arrays.
For a positive integer limit, scanning from the end can stop after enough matches,
then reverse the matches to preserve output order. Other limits need a compatible
fallback. Incorrect early exits and incorrect output order are rejected.

This is a real-function correctness target. Its cost baseline is an authored
forward-scan **IR implementation**, not timing of the native function. Interpreter
speedup must not be represented as a TypeScript performance gain.

### Beetle batch route readers

For each ordered address query, choose the nearest address with any routes. Within
that level return its first converse reader, otherwise its first route, otherwise
null. Keep all route fields and query order. The batch reads one immutable route
snapshot, allowing index construction to be amortized over queries.

The target tests algorithmic selection only. It does not model author authority,
audience visibility, journal recovery, subscription mutation or the rest of the
live router. Its oracle is a small reference port of the selection contract;
**native Rust conformance is still required** before a Beetle implementation.
All fixtures are synthetic and contain no private Slack or organizational data.

## A bounded language instead of arbitrary source execution

An `Algorithm` is serializable JSON with:

- JSON literals, variables, own-property reads and fixed intrinsics;
- assignment, conditionals, forward/reverse `for` loops, `break` and `return`;
- local arrays, append operations, and local string-keyed indexes;
- scalar comparisons, arithmetic, string filtering and array operations.

There is no `eval`, source import, native callback, clock, randomness or ambient
I/O in the candidate language. Loop bounds are snapshotted before iteration.
Inputs are isolated immutable JSON; local indexes cannot escape as output.
Syntax depth/size, interpreted steps and allocated cells are bounded. Costs for
collection/string intrinsics scale with their inputs; index build cost is charged.

The cell/step model is not an exact CPU or byte-memory limit. Parsing, JSON
serialization, oracle setup and host proposer work are outside the interpreted
step count. Proposers, references and integration adapters are trusted host code.
Do not execute externally generated JavaScript just because the IR interpreter
is bounded. A future source-code runner needs its own actual isolation boundary.

## Acceptance protocol

`searchAlgorithms(target, proposer, options)`:

1. Copies fixed training, validation and held-out cases; rejects duplicate inputs.
2. Obtains expected results from the independent reference, outside candidate code.
3. Tests the baseline and proposed candidates against training cases.
4. Gives the proposer only the contract and immutable training feedback.
5. Selects a fixed shortlist plus the baseline fallback and checks validation cases.
6. Chooses by validation work count, then tests that winner once on held-out cases.

A held-out failure sets `accepted: false`; it never triggers reselection. Incorrect
or over-budget candidates cannot win. A correct baseline remains an explicit
fallback. The archive records failed candidates and their work as well as winners.
The total step cap includes baseline, candidate, validation and final executions.
Exhausting that cap can abort the experiment rather than silently dropping checks.

Results are correctness evidence on finite cases, not a proof for all inputs.
Native timing, production distributions and effect-boundary conformance remain
separate verification steps.

## Proposers and additional targets

The built-in targets use authored structural grammars. Search discovers the best
candidate **within those grammars**; it does not establish invention of a globally
new algorithm. A model can propose a wider set of JSON algorithms through the
same interface, without gaining access to held-out cases or changing the evaluator.

```ts
const report = await searchAlgorithms(target, async context => {
// Supply an enumerator, a structural mutator, or a model adapter here.
// context contains { iteration, target: { id, contract }, archive }.
// Return { name, algorithm }, or undefined to finish.
return myProposer(context);
}, { maxProposals: 64, maxSteps: 1_000_000, maxTotalSteps: 30_000_000 });
```

To evaluate JSON generated by a coding agent or another process:

```sh
npm run algorithm:search -- --target fx-memory --proposals ./candidates.json
```

The file is an array of `{ "name": "candidate", "algorithm": { "version": 1,
"body": [...] } }` records. It is parsed as data, never imported as executable
JavaScript. Register another target by supplying its contract, baseline IR,
reference function and three fixed case splits. A natural-language wish alone
does not establish correctness or a useful optimization objective.

### Optional model-generated search

`createModelAlgorithmProposer(provider, options)` works with FX's existing
`LLMProvider.chat` interface. It supplies the language grammar, input contract,
baseline and bounded training feedback. Invalid responses are retained as
proposer errors; a call cap stops repeated generation. Reported usage includes
provider calls and token counts when supplied by that provider. There is no
monetary cap, and provider-internal retries are outside this call counter.

With an already configured `OPENAI_API_KEY`, the CLI can use the existing FX
chat-completions provider; `OPENAI_BASE_URL` optionally selects a compatible host:

```sh
npm run algorithm:search -- --target fx-memory --model YOUR_CHAT_MODEL --budget 16
```

The model must support the existing provider's chat options. Other providers can
be injected programmatically through `runTarget` or `searchAlgorithms`. This
implementation's provider tests use mocks; the checked-in results use the
deterministic grammar, and no live model run is claimed.

## Use a selected algorithm inside FX

```ts
import { createAgent, createPlan, algorithmStep, JsonValue } from '@fx/core';

type SearchState = { algorithmInput: JsonValue; algorithmResult?: JsonValue };

const agent = createAgent('selected-algorithm', createPlan('plan', [
algorithmStep<SearchState>(
report.selected.algorithm,
state => state.algorithmInput,
(state, result) => ({ ...state, algorithmResult: result })
)
]));
```

Supply a typed JSON input adapter appropriate to the target. Memory timestamps
must be normalized and restored by the adapter if the surrounding API uses Dates.
Running through the interpreter may be slower than native code even when the
selected algorithm performs fewer modeled operations. The next deployment gate
is a reviewed native implementation, conformance tests and representative timing.
191 changes: 191 additions & 0 deletions docs/advanced/program-discovery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# Experimental program discovery

For control-flow and indexing algorithm search targeting FX and Beetle, see
[Algorithm search](algorithm-search.md). That extension has a separate bounded
language with loops and branches; the numeric `Program` language below remains unchanged.

FX can now represent a bounded program as JSON, execute it as an ordinary FX
`Step`, search for programs against an external evaluator, and extract
parameterized abstractions from a successful program corpus. This is an
experimental research kernel, not a general self-improving agent.

No model, API key, coding agent, new dependency or production integration is
required for the included experiments. Node 18+ is required for the example
test runner (CI uses Node 20); the library remains compatible with the existing
package's target.

## Run it

From the repository root:

```sh
npm ci
npm run test:experiments
npm run experiment:transfer
npm run experiment:scheduling
```

The experiment commands build the package and print JSON. To save JSON without
build logs, build first and run the example directly:

```sh
npm run build
node examples/discovery/transfer.cjs > transfer.json
node examples/discovery/scheduling-discovery.cjs > scheduling.json
```

## Programs are data

```ts
import { createAgent, createPlan } from '@fx/core';
import { ProgramRuntime, Program, Abstraction } from '@fx/core/discovery';

type Counter = { readonly value: number };
const affine: Abstraction = {
name: 'affine', arity: 2,
body: [
{ op: 'add', args: [{ parameter: 0 }] },
{ op: 'scale', args: [{ parameter: 1 }] }
]
};
const runtime = new ProgramRuntime<Counter>([
{ name: 'add', arity: 1,
execute: (state, args) => ({ value: state.value + args[0]! }) },
{ name: 'scale', arity: 1,
execute: (state, args) => ({ value: state.value * args[0]! }) }
], [affine]);
const program: Program = {
version: 1, body: [{ op: 'affine', args: [3, 2] }]
};

runtime.expand(program); // add(3), scale(2)
runtime.run(program, { value: 4 }); // { state: { value: 14 }, primitiveCalls: 2 }
const agent = createAgent('discovered', createPlan('plan', [runtime.asStep(program)]));
await agent.start({ value: 4 }); // { value: 14 }
```

Version 1 has sequential calls, finite numeric arguments, and parameterized
abstractions. It deliberately has no arbitrary source evaluation, branches,
loops, general expression language or dynamic creation of native primitives.
It is possible to build other domains by registering trusted primitives.

The runtime validates the whole expanded program before executing a primitive.
Unknown names, incorrect arity, unbound parameters, recursive definitions,
excessive call depth and expanded operation overruns fail before execution.
Defaults: 1,024 expanded primitive calls, 32 abstraction levels, 128 instructions
per serialized body, 16 arguments per call.

States are isolated, deeply frozen JSON snapshots. Non-finite results,
non-JSON values and cycles are rejected. Primitives must be trusted synchronous
functions: the runtime cannot stop their JavaScript from accessing global state,
performing I/O or failing to return. Resource counts bound interpreted operations,
not CPU time or native memory. They are not a security sandbox or proof of purity.

## Abstraction learning

`learnAbstractions(successfulPrograms)`:

1. Deduplicates closed, expanded programs by canonical content hash.
2. Finds repeated contiguous operation structures.
3. Replaces varying literal columns with parameters. Columns that vary together
share a parameter; fixed constants remain constants.
4. Counts non-overlapping structural replacements.
5. Keeps candidates with positive description-length savings, charging both
call sites and the new definition (including its parameters).

Each result includes the definition, source program hashes, occurrence count,
compression gain and witnessed argument tuples. Results are independently scored
candidates, not an optimally selected joint library. The current miner is a
bounded contiguous-pattern learner, not Stitch or an e-graph implementation.

`abstractProgram` factors a program without changing its expansion.
`abstractionActions` constructs calls for witnessed argument tuples only.
A caller can supply new tuples after validating them. Structural compression
does not establish utility, semantic novelty, behavioral generalization or
authority to activate a policy. The caller must supply genuinely successful
programs and independently assess learned candidates.

## Search, evaluation and feedback

`enumeratePrograms(actions, maxLength)` is a deterministic proposer.
`searchProgram(runtime, examples, proposals, budgets)` accepts any iterable of
candidate programs, returns the first exact solution, and retains every attempted
candidate with its identity, outcome and expanded operation cost. Both candidate
and primitive-call budgets apply; failing primitive invocations are charged.
It refuses to start an example whose full expansion cannot fit the remaining
budget. Verification cases are kept outside this search API.

`optimizePrograms(proposals, evaluate, maxEvaluations)` selects the highest-scoring
valid candidate from a bounded proposal stream. `proposals` can also be a callback
`(archive, iteration) => program`, enabling outcome-guided mutations or an external
model adapter. A negative finite score is valid; invalid candidates cannot win.
Programs and scored feedback are frozen. Duplicates consume proposal budget but
are not evaluated twice. The budget counts proposals, not arbitrary computation
inside a trusted proposer or evaluator; domain experiments report that work
separately. The library has no built-in model training or automatic policy activation.

## Experiment 1: abstraction transfer

The initial eight arithmetic tasks are actually solved by primitive enumeration.
The resulting corpus supports an inferred two-parameter `add; scale` abstraction.
Eight distinct four-operation functions are withheld from that corpus. Search
receives three I/O examples per task and selected programs are checked against
five additional inputs, including a fractional and negative input.

Three arms receive the same per-task budgets (256 proposals, 1,024 primitive
calls, at most four symbolic instructions):

- Primitive operations only.
- The same operations plus eight saved, opaque training programs.
- The same operations plus calls to the learned parameterized abstraction.

Every macro expansion is checked to use the original primitive action vocabulary.
Learning costs are reported separately. The designed experiment currently gives
0/8, 8/8 and 8/8 solved tasks respectively. This demonstrates bounded search reuse
and correct factoring; it **does not demonstrate an advantage over saved snippets**.
Vocabulary order and the symbolic search horizon affect the result. A stronger
next experiment must show useful new bindings or structures beyond that baseline.

## Experiment 2: GPU scheduling policy discovery

The discrete-event simulator models arrivals, heterogeneous worker speeds,
memory eligibility, per-tick prices, deadlines, and persistent model caches
with a four-tick reload cost. One job occupies one worker slot. Every run checks
for lost or duplicated jobs. Tests independently check overlapping assignments,
memory constraints, arrival ordering and a manually calculated timing/cost witness.

A policy scores eligible job/worker pairs using a program over duration, estimated
cost, waiting time, remaining deadline slack and model-load cost. Policies are
linear weighted feature combinations. They cannot change simulator physics or
the external evaluator. The authored objective, minimized, is:

```text
mean flow time + 0.25 * mean tardiness + 0.08 * total monetary cost
```

The adaptive proposer mutates high-scoring programs from its archive. A separate
random-search control uses the same proposal budget, initial baseline policies
and vocabulary. Both use six training scenarios, then select from a fixed
shortlist on four different validation scenarios. Final evaluation uses twelve
untouched workloads across mixed, burst, long-job and many-model regimes.

Reports retain all six authored heuristics (FIFO, shortest duration, earliest
deadline, locality, cheapest placement and a cost/locality hybrid), the random
control, discovered programs, per-regime results and primitive-call costs.
Do not interpret the best aggregate as winning every metric or workload.
There are no production traces, native conformance tests, network failures,
retries, cancellations or confidence intervals. This experiment demonstrates
evaluator-guided policy search, not abstraction transfer or a production scheduler.

## Next research gates

- Parameterized libraries must outperform saved snippets and a strong program
search baseline under matched discovery costs on unseen task structures.
- Adding library candidates must improve future search more than their discovery,
validation, storage and vocabulary-expansion costs.
- Scheduling gains must survive multiple search seeds, stronger optimization
baselines, new workload distributions and production-trace simulation.
- Effect contracts and semantics-preserving rewrites require explicit semantics;
the existing `Context -> Context` type does not establish either property.

These gates are experiments to run, not capabilities claimed by this version.
Loading
Loading