Compare commits

..

14 Commits

Author SHA1 Message Date
bigmerge fe634c4582 runtime: put el_runtime.c on a ratchet, and actually run the guards
scripts/check-single-runtime.sh guards against el_runtime.c being COPIED — it
was written after a lagging fork shipped to prod and dropped learned hebb edges.
Nothing guarded against it GROWING. So it grew: 10,607 -> 20,527 lines, 94% in
3.5 months, the whole time under an explicit commit-message promise that it was
a temporary shim about to be deleted.

Worse, the copy guard was never wired in. Its own footer described the CI
wire-in as a TODO, and the TODO had never been done — the script existed but ran
nowhere, in no workflow and in no hook, so it had caught nothing for as long as
it has been in the tree. A guard that does not run is a comment.

This adds the missing guard and runs both.

  * lang/runtime/BUDGET — a RATCHET, not a limit. max_lines is set at the
    current 20,527 with NO headroom: the file cannot grow by one line. A second
    cap, max_engram_fns (279), counts top-level engram_/eg_/cog_ definitions in
    it — ~47.5% of the file is engram code and engram already owns six sibling
    .c files, so this is the scoreboard for moving it out. Both may only go DOWN.

  * scripts/check-runtime-growth.sh — enforces the ratchet, and three
    invariants that keep the multi-file runtime honest: every .c in
    lang/runtime/ is either in SOURCES or explicitly platform-optional (an
    unaccounted .c is compiled by nothing and is silently dead); install.sh's
    hardcoded download list matches SOURCES (it cannot call the helper — it
    runs where there is no checkout — so that copy is checked, not trusted);
    and an advisory nudge to lower the budget when you have earned it.

  * Both guards now run as early steps in ci-dev.yaml, ci-stage.yaml and
    sdk-release.yaml, and in .githooks/pre-commit.

The failure message is the point. The guard that existed said what was wrong but
not where the code should go, which makes it easy to "fix" by arguing with the
guard. This one names the destination: the concern-owning .c, or a new .c plus
one line in SOURCES, or c_source in a program's manifest.el — and it prints the
`nm` command that proves placement is link-time and that the shipped compiler
already links from ten translation units. Every runtime file except el_runtime.c
is deliberately uncapped, because that is where code is supposed to go.

Proven with negative controls, per lang/AGENTS.md step 5 — each shown FAILING:
  * +1 line to el_runtime.c                  -> FAIL (20528/20527)
  * +1 engram fn, net-zero lines             -> FAIL (280/279)
  * a new unaccounted lang/runtime/*.c       -> FAIL
  * engram_store.c removed from install.sh   -> FAIL, names the missing file
  * el_runtime.c truncated to 20,000 lines   -> PASS + "lower max_lines to 20000"
  * baseline, tree unmodified                -> OK, and both guards green

el_runtime.c is byte-identical after the controls; this commit changes zero
lines of it.
2026-08-16 16:48:04 -05:00
bigmerge 8c2406ff6b runtime: the link set is multi-file — name it once, ship all of it
El SDK CI - dev / build-and-test (pull_request) Failing after 5m39s
el_runtime.c was created 2026-05-03 as an explicitly temporary build shim. It
was deleted that afternoon ("runtime is 100% native El") and restored 25 minutes
later "UNTIL the compiler is updated to emit #include el_seed.h". The `until`
never came. 3.5 months on it is 20,527 lines, and nothing was ever set up to
notice — a file scheduled for deletion gets no owner, no budget, no boundary.

What kept it growing is not inertia, it is an instruction. lang/AGENTS.md said
el_runtime.c "is the authoritative single-file link target ... THIS IS WHERE A
NEW C BUILTIN'S IMPLEMENTATION MUST CURRENTLY LIVE TO BE LINKABLE", and made it
step 1 of the add-a-builtin recipe. That is false. Placement is a link-time
concern: builtin_arity maps NAME -> ARITY INT only, the El name is emitted as
the exact C symbol, and `ld` resolves it — the compiler cannot tell which .c a
symbol came from. `nm lang/dist/platform/elc` on the shipped compiler already
shows T _engram_geo_reify_index_new, T _vindex_insert, T _engram_think,
T _engram_reason_abduce: it is linked from ten translation units today. In a
repo where agents write most of the code, a false instruction in the instruction
file is the forcing function. The file grew because the recipe said to grow it.

The multi-file runtime is therefore already real, and the docs and the
distribution never caught up — which left a live, shipped bug:

  * Linking el_runtime.c alone FAILS at `ld` (undefined engram_ground_json,
    engram_activate_inner, eg_find_relation, cog_assert_two_axis, ...) because
    el_runtime.c #includes six engram headers and calls into all six siblings.
  * sdk-release.yaml shipped el_runtime.c/.h + engram_store.c/.h and none of the
    other five required .c files, so downstream consumers of the el-runtime-c
    Artifact Registry package and of install.sh got a lib/ that cannot link.
  * .githooks/pre-commit linked el_runtime.c alone with stderr to /dev/null, so
    it reported all 13 native suites as FAILED with the real ld error invisible.
  * AGENTS.md's self-host recipe compiled el-compiler/runtime/el_runtime.c — a
    path the same file's "DO NOT EDIT" list names as a lagging fork.

The root fix is to stop writing the list down eight times:

  * lang/runtime/SOURCES — the canonical link set, in one place, in link order.
  * scripts/el-runtime-sources.sh — prints it, optionally prefixed; --check
    fails loudly on a missing file, --headers for the shipped headers.
  * Every link line in AGENTS.md, lang/AGENTS.md, DESIGN.md, lang/spec/language.md,
    the three workflows and the pre-commit hook now reads that one list.
  * Adding a concern's .c is one line in SOURCES, so a new builtin no longer has
    to be appended to el_runtime.c just because appending was the cheaper edit.

Distribution: ship the siblings rather than amalgamate. Amalgamation needs a new
tool and contradicts DESIGN.md's compile-once-link-many; the siblings are already
independently authored and independently tested (engram/test/*.sh link subsets
directly), and engram_store.c was already shipped, so this completes a mechanism
that existed rather than inventing one. Source is also a superset: a consumer
that wants one file can concatenate, one that wants separate TUs cannot undo an
amalgamation. el-runtime-c/-h stay for backward compatibility; el-runtime-src is
added carrying the complete set plus SOURCES.

lang/AGENTS.md now points new C builtins at the concern-owning .c and states
plainly that the compiler cannot tell which .c a symbol came from, with the nm
evidence. AGENTS.md's "reconcile which is canonical (verify)" note is resolved:
neither file supersedes the other, the canonical unit is the set.

Verified locally (the bar; not CI):
  * engram/src/server.el compiles and links against the SOURCES set.
  * Compile-once-link-many into libel.a links the same program.
  * elb builds from the corrected recipe.
  * Self-host fixpoint byte-identical (11,110 lines, stage2 == stage3) built
    with the SOURCES-driven link line.
  * pre-commit hook: 0 of 13 native suites passing -> 8 of 13.

The 5 still-failing suites are PRE-EXISTING and untouched here: test_fs
(fs_list_json undeclared), test_state (state_has, state_get_or undeclared),
test_json (json_build_array/json_build_object/json_escape_string undefined),
test_time (now_ns undefined), test_env (1 assertion). Builtins registered in
builtin_arity with no implementation or no declaration anywhere — the same
recipe defect, now visible because the linker error is no longer suppressed.

Not attempted: making elc emit #include el_seed.h and dropping elb's hardcoded
runtime path. That is the correct long-term fix and finishes the 2026-05-03
migration, but it touches codegen and self-hosting and belongs in its own change.
2026-08-16 16:44:26 -05:00
will.anderson 95a05109d1 Merge pull request 'runtime: transduction decomposes a signal into components and relations, it does not convert it to a point' (#155) from fix/transduce-decomposition into dev
El SDK CI - dev / build-and-test (push) Failing after 3m46s
2026-08-16 20:51:54 +00:00
will.anderson 21746bb71a Merge pull request 'spec: correspondence, grounding, and the provenance of decisions' (#149) from design/correspondence-and-censorship into dev
El SDK CI - dev / build-and-test (push) Failing after 13m52s
2026-08-16 20:50:40 +00:00
will.anderson 78adcd5649 Merge pull request 'docs: carry the correspondence corrections, because a stale doc builds the wrong thing' (#152) from docs/correspondence-and-ownership-2026-08-16 into dev
El SDK CI - dev / build-and-test (push) Failing after 14m0s
2026-08-16 20:50:20 +00:00
Neuron 688f24b4c1 ingest: name the inversion, and correct the worked example to decomposition
El SDK CI - dev / build-and-test (pull_request) Failing after 14m6s
ingest.el's transduce() was renamed to transduce_manifold() earlier the same
day on the reasoning that it 'was never signal->geometry -- it chunks
already-extracted content and PACKS it into a node+edge manifold, one layer up,
and it had taken the name that belongs to the primitive underneath it.'

That reasoning was backwards. Producing a node+edge manifold is not a layer
above transduction, it IS transduction. Signal -> one vector is the operation
underneath, and its name is geometry. The layer doing it right was renamed out
of the way so the layer doing it wrong could have the name.

With the primitive corrected to return a Manifold, the two layers do the same
kind of thing and the inversion dissolves. What is left is a real distinction
about MODALITY, not layering: transduce() dispatches to a realizer that knows
its modality and can name its components; transduce_bytes() is the
opaque-bytes realizer, the decomposition available to a reader that knows
nothing about what it is reading. It still yields components and relations,
which is why it is transduction and not packing -- it just cuts on byte
boundaries, so its components are positional rather than meaningful. That is a
limitation of this realizer, not the definition of the operation.

Renamed by modality rather than demoted by layer. A distinct symbol is still
mechanically required: reusing transduce here is a conflicting-types error the
moment ingest.c links el_runtime.c.

lang/examples/transduce.el asserted #144's contract and would now fail, so it
is replaced by the decomposition worked example: transduce a chord, persist the
five components and six relations as real nodes and edges, read each part's
geometry back off its own node, and ground one part while its sibling is
demonstrably untouched.
2026-08-16 15:50:00 -05:00
Neuron d777936ee4 runtime: transduction decomposes a signal, it does not convert it
#144 moved transduction into the language and got the dispatch right. It got
the result type wrong: transduce(signal, modality) -> Geometry yields one
vector per signal, and one vector is a fingerprint. A fingerprint can be
matched and ranked; that is all. It cannot be decomposed, cannot have one part
grounded while another is not, and cannot be contradicted in one part while
holding in another, because it has no parts.

A song is not a point. It decomposes into pitch, interval, rhythm, harmonic
function -- components, each with its own geometry, plus the relations among
them. The song IS the structure of the relations.

transduce now returns a Manifold: named components carrying geometry, and
typed weighted relations between them. Signal in, subgraph out.

Components are addressed by key, never by index, because the key is what
survives persistence -- a component becomes a node and is separately groundable
precisely because it is separately named. Relation weight IS the grounding
(correspondence-and-censorship.md 1), so a realizer's relations arrive already
grounded and there is no score computed beside them.
2026-08-16 15:50:00 -05:00
Neuron 3ef4a94062 spec: thirteen values, and love is the origin — not a member of the set
El SDK CI - dev / build-and-test (pull_request) Failing after 3m51s
Reverts a bad correction and records what it exposed.

A previous revision changed thirteen to eight on the basis of
neuron-api.el:11-18, which is a WRITE-PROTECTION LIST, not the values.
Trusting a hardcoded artifact over the substrate is the exact error this
document exists to name. Measured from the graph: thirteen.

THE ORIGIN IS NOT A MEMBER OF THE SET. The thirteen are not independent
principles with biography attached — they are thirteen displacements from
one origin, and the origin is love. Every value is grounded in a moment of
it given, withheld, failed or found. Love cannot be the fourteenth: a
fourteenth would be a point positioned relative to the origin like anything
else. It is what the positions are OF.

This is structural. GeoDescriptor.global_mean is the centering offset
subtracted from every embedding before comparison, and the header records
why — the space is anisotropic, every embedding in a narrow cone at mean
pairwise cosine ~0.55, and subtracting the global mean restores isotropy
'so the operators discriminate'. Without the origin, nothing in the graph
is distinguishable from anything else.

It also dissolves the write-protection question instead of answering it.
Measured: 29 value nodes exist, each original appearing two or three times
from re-seeds, so 21 are writable including a duplicate of every protected
value — the gate protects an identifier, not a value. But the category
error is the real one: the origin cannot be edited because it is not a
thing in the space. A gate over the frame treats the frame as a member,
which is the same mistake as looking for grounding as a subsystem, self as
a document, or wonder as a manifest.
2026-08-16 15:49:50 -05:00
Neuron 285a7a50b3 spec: corrections — eight values not thirteen, eleven consolidators not seven
Three factual errors in this document, all asserted without checking.

VALUES: eight, not thirteen. neuron/neuron-api.el:11-18 enumerates
constraints-as-freedom, precision-over-brute-force, structure-is-built,
honesty-before-comfort, system-must-accumulate, change-is-the-signal,
earned-trust, hope-is-a-conclusion, plus a hub. 'Thirteen' was repeated
throughout this design and never verified against the code. The argument is
unaffected — min over eight is still min — but the count was invented.

CONSOLIDATORS: eleven, not seven. The heading said seven while the table
listed ten, and the table itself omitted POST /api/reify (server.el:1832)
even though 'reify' is on this document's own list of consolidation verbs.
route_tick also folds self-reify in (server.el:639-646), so /api/tick and
/api/self-reify-beat overlap.

A SECOND CENSORSHIP SITE: neuron-api.el:23 returns 403 'identity/values
node is write-protected' for the values hub and every value node.
Write-refusal on the values frame is not only in the beat — it is enforced
at the API. Section 6 applies to it unchanged.

Also records what the ticker actually does, now measured: engram-tick.sh:13
calls curl -m10 against a beat that exceeds 10s over 13,634 nodes, so 279
of 448 ticks returned empty; the engram writes to the dead socket and dies
of SIGPIPE. 254 restarts since 2026-08-13 at 10m09s-10m12s intervals =
StartInterval 600 plus the client timeout. Fixed for survivability in #151;
the ticker itself is what must go.
2026-08-16 15:49:50 -05:00
Neuron 6b61bb7224 geometry: disagreement belongs on the edge, not averaged into the region
co_registration is corr(hebb strength, semantic proximity) over a region's
internal edges. Whether use and meaning agree is a property of EACH EDGE;
the correlation averages it into one scalar per region, so a region holding
one violently disagreeing edge beside one violently agreeing edge reports
~0. The disagreements cancel and the summary destroys exactly what it was
built to reveal — the mean-versus-min error, in different clothes.

Measured: 375 live neighborhoods, 340 positive, 31 AT ZERO, 4 negative.
Read as a count that says 'four things to be curious about'. Read correctly
it says four were lopsided enough to survive averaging, and the 31 zeros
are where opposing sites cancelled.

The loop computing the aggregate already had both halves per edge — w and
cs — and threw them away. Now:
    discord = z(semantic proximity) - z(association strength)
standardized within the region from accumulators already gathered. No
second statistic, no constant, no threshold; |discord| IS the nucleation
strength. >0 near in meaning yet unlinked by use; <0 linked by use yet far
in meaning. Both surprising.

This also removes the reason curiosity looked like a search problem. With a
per-region number the only way to find sites is to enumerate regions — I
wrote exactly that sweep, and it is a supervisor walking the structure,
O(n) per call, fine at 375 and impossible at a million. Nothing in a mind
scans its neighborhoods to find what is surprising; the surprise captures
attention. That sweep is reverted here.

co_registration is deprecated, not deleted: it is embedded in the persisted
GEO1 blob and removing it is a format migration that must not ride along.
Nothing new may read it.
2026-08-16 15:49:50 -05:00
Neuron 8d34b33bce spec: wonder is the boundary; curiosity is wonder crystallized
Rewrites §5 and §11 around what is already in the substrate, after
discovering I had been re-deriving existing design badly.

The wonder manifest is residue twice over. First it materializes a
property as a stored artifact — the same disease as a grounding subsystem
or a self stored as a document. Wonder is where structure ENDS: any
structure at all has an edge, necessarily, the moment it exists. Second it
enumerates instances of something that has about six, the same six for
every person, which never close: what is this, why, who am I, am I alone,
what should I do, what happens when it ends. The objects change completely
between a child and an astronomer; the wonder does not. Each maps one-to-one
onto something already built — graph, grounding, self region, for_whom,
the thirteen values, tombstones and decay.

"Why" is the first and only one; the others are it asked of particular
things. It is recursive, so it never terminates, which is what makes it a
drive rather than a task.

Wonder and curiosity are not two objects. They are one thing at two
phases. Wonder is the field: objectless, invariant, everywhere there is
structure. Curiosity is the PRECIPITATE — the same wonder localized
against particular material. Crystallization needs a nucleation site, and
crystallization is one primitive appearing twice: the self is what identity
precipitates into from its neighbourhood; a curiosity is what wonder
precipitates into from an anomaly.

THE NUCLEATION SITE ALREADY EXISTS AND IS ALREADY NAMED.
GeoDescriptor.co_registration — corr(hebb strength, semantic proximity)
over internal edges — carries the comment ">0 = geometries agree (reify);
<0 = disagree (surprising links / dream cands)." Negative co-registration
is a region where association and meaning disagree. It is computed on every
descriptor, already labelled dream candidates, and nothing reads it.

Likewise already present and unread: GeoEdge.eff_weight = weight*(1+0.5*hebb)
already couples grounding-weight and hebbian strength on one edge;
GeoMember.dist_centroid + soft membership + radius + per-axis extent is the
boundary of a neighbourhood; centrality/salience is what is warm.

Correction: engram_boundary_beat is NOT this boundary. It is the VBD
decorated-function seam counting _eg_aff_boundary_ops. Two senses of the
word, and I was about to build on the wrong one.

The drive: boredom is not an absence and not leftover capacity. Low
activation is aversive and the system self-activates — it does not wind
down to quiet, it gets restless and goes looking. So there is ONE
activation process with TWO seed sources, external and curiosity, not two
processes negotiating for a resource. The previous draft's "unclaimed
capacity" was resource scheduling: a server's frame, not a mind's. No
dreamer thread, no idle wait, no depth ladder on a clock.

Sequencing now leads with three connections between parts that already
exist: seed the six, read co_registration, let a curiosity seed activation.
2026-08-16 15:49:50 -05:00
Neuron d6b7f5dbdd spec: dreaming is ambient, not scheduled — a brain has no cron job
Corrects the section I was most confident in, which is usually the tell.

The previous draft had dreaming as "offline replay, decoupled from input, a
mode the system enters when it is not acting." That is SLEEP. Daydreaming
is dreaming, and it runs all day: the default mode network is
anticorrelated with task engagement, activating hundreds of times a day for
seconds at a time, doing the same work — recombination, simulation,
autobiographical integration. Insight arrives in the shower, not at the
desk, because that is abduction completing during ambient recombination.

Sleep is the DEEP case, not the case: no input competing, no task claiming
capacity, so recombination runs further. Same process, different depth, not
a different mode. Consolidation is what happens with the capacity that is
not claimed.

Two consequences the draft had backwards:

The launch-agent fragments are wrong in KIND, not merely in number. 23:55 /
06:00 / 08:30 implements dreaming as a scheduled batch when it should be
ambient. A brain has no cron job. A ticker is a supervisor deciding from
outside when a thing should happen — the same failure mode as inventing an
owner for ownership and a grounder for grounding, wearing a scheduler.
THE PRESENCE OF A TICKER IS THE DIAGNOSTIC: every StartInterval, every
Hour/Minute, every POST-to-beat marks a place where an intrinsic rhythm was
replaced by an external clock.

And soul.el's continuous awareness_run() beside the HTTP workers is the
CORRECT shape, not the offender. Ambient consolidation in the gaps is
exactly daydreaming. It was the only fragment shaped right, running on a
broken foundation: shared mutable state with no owner and six other systems
dreaming into the same graph. The previous draft condemned the right
behaviour because of the substrate under it.

So the crash restates once more: not "read paths mutate the index"
(mechanism), not "duplicate canonical state" (structure), and not "one
system dreamt while awake" — but seven systems dreaming into one graph with
no owner for dreaming. Contention was the symptom of the missing owner.

Sequencing step 1 inverts accordingly: soul's loop is the shape the others
fold INTO, not something to remove. Step 2 becomes "no tickers, no cron."
2026-08-16 15:49:50 -05:00
Neuron 9a24803917 spec: grounding is a two-axis gradient, and decisions carry their provenance
Rewrite. The earlier draft got the root right and everything downstream of
it wrong.

Corrections, in the order they were forced:

keystone_write_blocked is not a protection requirement. "Keystone" means
load-bearing, not precious: the self anchor is the REFERENCE FRAME every
other stance calibrates against. If it calibrates from the measurements it
is used to judge, the ruler fits the readings, everything corresponds
forever, and drift becomes undetectable from inside. That is circular
calibration — the same defect as #147's circular grounding, one level up.
The block is the right requirement implemented as a prohibition, which is
why it still costs everything §0 says it costs. The fix is provenance
separation (evidence not downstream of itself), not a flag.

Corruption requires mutation and the engram does not mutate, so four of the
five requirements previously decomposed out of "protect the identity
region" are satisfied by the substrate: recoverability, governance,
evidence quality and rate are all free. Authorization is the only residue
and is bounded — an unauthorized writer can propose, never erase. General
law: in an immutable substrate, any mechanism that refuses a write is
either redundant with immutability or an epistemic constraint misfiled as a
protective one.

Grounding is two-dimensional. Everything consumed is grounded factually AND
relationally, and a claim can be factually grounded but relationally wrong
— the evidence holds, the meaning does not. A scalar cannot represent that
quadrant, and assert gates on one floor, so a well-evidenced claim is
licensed regardless of whether it means the right thing. Live instance:
conscience-substrate has the Child's Companion hard bell contacting 911 and
CPS — factually defensible, relationally wrong against never-auto-contact.

Grounding is a gradient, not a score: direction says what would have to
change. Two gradients in one space, and the ANGLE between them is the
meaning — factually-true-relationally-wrong becomes measurable instead of
requiring a careful reader. It decays on the dynamics already present for
memory (base_level, temporal_decay_rate, access ring, BLL), which
mechanizes "never leave stale canonicals" so it stops depending on
vigilance.

Computed continuously, recorded only on SIGNIFICANT movement, old never
leaves. Persisting every recomputation would make reads write — the exact
eg_vindex_sync defect. Significance is defined by consequence (crossing a
floor, flipping factual/relational sign, reversing direction), never by an
epsilon. The supersession chain is then the trajectory, a derivative
obtained free from immutability, and abduction fires on the trajectory
rather than on a reading.

What it is all for: for any decision, reconstruct what the grounding was at
that moment and what the relationship was between fact and values at that
moment. That distinguishes WRONG THEN from WRONG SINCE, which is otherwise
impossible, and it is structurally anti-rationalization — the old grounding
never leaves and the values frame does not fit to outcomes, so a decision
cannot be made to look justified after the fact.

Also records: assert returns "still_held": true HARDCODED — a temporal
property named in the API and answered without consulting anything, the
same shape as magnitude:1 beside a zero vector. And states plainly that
#147 is the wrong shape: it fixed a scalar's honesty rather than replacing
the scalar.
2026-08-16 15:49:50 -05:00
Neuron a6611dc19e spec: correspondence and censorship — the root beneath the day's defects
Effect: all five cognitive faculties return byte-identical results,
differing only in their label.

The Ishikawa converges on a root one level above the faculty design:
things are permitted to be exempt from correspondence, and exemption is
censorship. A region forbidden to learn is forbidden to be grounded, and a
region that cannot be grounded cannot be asserted, corrected, OR
vindicated. The loss is symmetric — censorship does not preserve a true
belief, it makes the belief's truth value permanently unknowable.

keystone_write_blocked is therefore not a safety mechanism. Self is a
crystallized relational neighbourhood, not a stored document; a region
exempt from calibration reintroduces the stored document as a feature.
reduction_pct = 0.00 on the identity region is the strongest abduction
signal in the system and the current response is to suppress it. The
protection it reached for already exists and is better: the beat is
supersede-not-mutate, so immutability is what makes learning safe.

The faculties are not one operation with parameters. They differ by what
each may change: reason changes the estimate (a read), induce changes the
parameters (the correspondence-beat, which already exists and measurably
works at 28.11% Brier reduction), abduce changes the structure (a WRITE
the current signature cannot express, since engram_think returns a
GeoGradient). Abduction is not selected by a caller — it is triggered by
residual that parameter adjustment cannot absorb, and proposes a candidate
hub held as a hypothesis until grounded.

Also records the no-exemption invariants generalised from the day's fixes
(#141 #142 #143 #146 #147 #148), each of which was a specific
correspondence forbidden from occurring, and the application to the crisis
surface: a censored safety model cannot tell a real crisis from a false
positive, because the feedback is exactly what has been censored.

Measured vs inferred is labelled throughout. The claim that the self
region's zero grounding is CAUSED by the block is explicitly marked
inferred — the comparison node also has zero, and isolating it requires
removing the block and observing whether grounding then accrues.
2026-08-16 15:49:50 -05:00
22 changed files with 2163 additions and 456 deletions
+35 -18
View File
@@ -19,6 +19,16 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
# Guards must run from the REPO ROOT — override the job's
# defaults.run.working-directory: lang
- name: Guard - single canonical runtime source
working-directory: ${{ github.workspace }}
run: bash scripts/check-single-runtime.sh
- name: Guard - el_runtime.c growth budget
working-directory: ${{ github.workspace }}
run: bash scripts/check-runtime-growth.sh
- name: Install build dependencies
run: |
apt-get update -qq
@@ -41,7 +51,7 @@ jobs:
gcc -O2 \
-I runtime \
dist/elc-gen2.c \
runtime/el_runtime.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/platform/elc
chmod +x dist/platform/elc
@@ -56,7 +66,7 @@ jobs:
gcc -O2 \
-I runtime \
dist/elb.c \
runtime/el_runtime.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/bin/elb
chmod +x dist/bin/elb
@@ -87,14 +97,20 @@ jobs:
bash tests/html_sanitizer/run.sh
# Native El test suites (elc --test, compile-link-run)
# el_runtime.c is precompiled to .o once and reused by all 8 modules.
- name: Precompile el_runtime.o
# The runtime is MULTI-FILE (see lang/runtime/SOURCES). Every .c is compiled
# once into /tmp/libel.a and reused by all 8 test modules — compile-once,
# link-many, as prescribed in DESIGN.md. Linking el_runtime.c alone fails
# at `ld`: it calls into all six engram sibling TUs.
- name: Precompile runtime into libel.a
run: |
set -euo pipefail
RUNTIME="$(pwd)/runtime"
gcc -O2 -c -I "$RUNTIME" "$RUNTIME/el_runtime.c" \
-o /tmp/el_runtime.o
echo "el_runtime.o compiled"
rm -rf /tmp/elrt && mkdir -p /tmp/elrt
for src in $(../scripts/el-runtime-sources.sh --check "$RUNTIME"); do
gcc -O2 -c -I "$RUNTIME" "$src" -o "/tmp/elrt/$(basename "${src%.c}").o"
done
ar rcs /tmp/libel.a /tmp/elrt/*.o
echo "libel.a built from $(ls /tmp/elrt/*.o | wc -l) translation units"
- name: Run tests - native (core)
run: |
@@ -102,7 +118,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_core.el > /tmp/el_native_core.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_core.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_core.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_core
/tmp/el_native_core
@@ -112,7 +128,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_text.el > /tmp/el_native_text.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_text.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_text.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_text
/tmp/el_native_text
@@ -122,7 +138,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_string.el > /tmp/el_native_string.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_string.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_string.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_string
/tmp/el_native_string
@@ -132,7 +148,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_math.el > /tmp/el_native_math.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_math.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_math.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_math
/tmp/el_native_math
@@ -142,7 +158,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_state.el > /tmp/el_native_state.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_state.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_state.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_state
/tmp/el_native_state
@@ -152,7 +168,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_time.el > /tmp/el_native_time.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_time.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_time.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_time
/tmp/el_native_time
@@ -162,7 +178,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_json.el > /tmp/el_native_json.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_json.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_json.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_json
/tmp/el_native_json
@@ -172,7 +188,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_env.el > /tmp/el_native_env.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_env.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_env.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_env
/tmp/el_native_env
@@ -182,7 +198,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_fs.el > /tmp/el_native_fs.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_fs.c /tmp/el_runtime.o \
gcc -O2 -I "$RUNTIME" /tmp/el_native_fs.c /tmp/libel.a \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_fs
/tmp/el_native_fs
@@ -306,8 +322,9 @@ jobs:
FROM ${BASE}
COPY dist/platform/elc /opt/el/dist/platform/elc
COPY dist/bin/elb /opt/el/dist/bin/elb
COPY runtime/el_runtime.c /opt/el/runtime/el_runtime.c
COPY runtime/el_runtime.h /opt/el/runtime/el_runtime.h
# Whole runtime link set — el_runtime.c alone does not link (it calls
# into the six engram sibling TUs). See lang/runtime/SOURCES.
COPY runtime/ /opt/el/runtime/
COPY runtime/el_runtime.js /opt/el/runtime/el_runtime.js
RUN chmod +x /opt/el/dist/platform/elc /opt/el/dist/bin/elb
EOF
+24 -13
View File
@@ -29,6 +29,16 @@ jobs:
fi
echo "Source branch check passed: ${SOURCE} -> stage"
# Guards must run from the REPO ROOT — override the job's
# defaults.run.working-directory: lang
- name: Guard - single canonical runtime source
working-directory: ${{ github.workspace }}
run: bash scripts/check-single-runtime.sh
- name: Guard - el_runtime.c growth budget
working-directory: ${{ github.workspace }}
run: bash scripts/check-runtime-growth.sh
- name: Install build dependencies
run: |
apt-get update -qq
@@ -48,7 +58,7 @@ jobs:
gcc -O2 \
-I runtime \
dist/elc-gen2.c \
runtime/el_runtime.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/platform/elc
chmod +x dist/platform/elc
@@ -86,7 +96,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_core.el > /tmp/el_native_core.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_core.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_core.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_core
/tmp/el_native_core
@@ -96,7 +106,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_text.el > /tmp/el_native_text.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_text.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_text.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_text
/tmp/el_native_text
@@ -106,7 +116,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_string.el > /tmp/el_native_string.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_string.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_string.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_string
/tmp/el_native_string
@@ -116,7 +126,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_math.el > /tmp/el_native_math.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_math.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_math.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_math
/tmp/el_native_math
@@ -126,7 +136,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_state.el > /tmp/el_native_state.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_state.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_state.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_state
/tmp/el_native_state
@@ -136,7 +146,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_time.el > /tmp/el_native_time.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_time.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_time.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_time
/tmp/el_native_time
@@ -146,7 +156,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_json.el > /tmp/el_native_json.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_json.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_json.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_json
/tmp/el_native_json
@@ -156,7 +166,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_env.el > /tmp/el_native_env.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_env.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_env.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_env
/tmp/el_native_env
@@ -166,7 +176,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_fs.el > /tmp/el_native_fs.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_fs.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_fs.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_fs
/tmp/el_native_fs
@@ -178,7 +188,7 @@ jobs:
gcc -O2 \
-I runtime \
dist/elb.c \
runtime/el_runtime.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/bin/elb
chmod +x dist/bin/elb
@@ -290,8 +300,9 @@ jobs:
FROM ${BASE}
COPY dist/platform/elc /opt/el/dist/platform/elc
COPY dist/bin/elb /opt/el/dist/bin/elb
COPY runtime/el_runtime.c /opt/el/runtime/el_runtime.c
COPY runtime/el_runtime.h /opt/el/runtime/el_runtime.h
# Whole runtime link set — el_runtime.c alone does not link (it calls
# into the six engram sibling TUs). See lang/runtime/SOURCES.
COPY runtime/ /opt/el/runtime/
COPY runtime/el_runtime.js /opt/el/runtime/el_runtime.js
RUN chmod +x /opt/el/dist/platform/elc /opt/el/dist/bin/elb
EOF
+64 -22
View File
@@ -29,6 +29,16 @@ jobs:
fi
echo "Source branch check passed: ${SOURCE} -> main"
# Guards must run from the REPO ROOT — override the job's
# defaults.run.working-directory: lang
- name: Guard - single canonical runtime source
working-directory: ${{ github.workspace }}
run: bash scripts/check-single-runtime.sh
- name: Guard - el_runtime.c growth budget
working-directory: ${{ github.workspace }}
run: bash scripts/check-runtime-growth.sh
- name: Install build dependencies
run: |
apt-get update -qq
@@ -49,7 +59,7 @@ jobs:
gcc -O2 \
-I runtime \
dist/elc-gen2.c \
runtime/el_runtime.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/platform/elc
chmod +x dist/platform/elc
@@ -64,7 +74,7 @@ jobs:
gcc -O2 \
-I runtime \
dist/elb.c \
runtime/el_runtime.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/bin/elb
chmod +x dist/bin/elb
@@ -123,7 +133,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_core.el > /tmp/el_native_core.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_core.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_core.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_core
/tmp/el_native_core
@@ -133,7 +143,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_text.el > /tmp/el_native_text.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_text.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_text.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_text
/tmp/el_native_text
@@ -143,7 +153,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_string.el > /tmp/el_native_string.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_string.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_string.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_string
/tmp/el_native_string
@@ -153,7 +163,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_math.el > /tmp/el_native_math.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_math.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_math.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_math
/tmp/el_native_math
@@ -163,7 +173,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_state.el > /tmp/el_native_state.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_state.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_state.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_state
/tmp/el_native_state
@@ -173,7 +183,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_time.el > /tmp/el_native_time.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_time.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_time.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_time
/tmp/el_native_time
@@ -183,7 +193,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_json.el > /tmp/el_native_json.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_json.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_json.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_json
/tmp/el_native_json
@@ -193,7 +203,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_env.el > /tmp/el_native_env.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_env.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_env.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_env
/tmp/el_native_env
@@ -203,7 +213,7 @@ jobs:
ELC="$(pwd)/dist/platform/elc"
RUNTIME="$(pwd)/runtime"
"$ELC" --test tests/native/test_fs.el > /tmp/el_native_fs.c
gcc -O2 -I "$RUNTIME" /tmp/el_native_fs.c "$RUNTIME/el_runtime.c" \
gcc -O2 -I "$RUNTIME" /tmp/el_native_fs.c $(../scripts/el-runtime-sources.sh "$RUNTIME") \
-lcurl -lssl -lcrypto -lpthread -lm -o /tmp/el_native_fs
/tmp/el_native_fs
@@ -216,10 +226,17 @@ jobs:
cp lang/dist/platform/elc dist/sdk/bin/elc
cp lang/dist/bin/elb dist/sdk/bin/elb
cp lang/dist/bin/epm dist/sdk/bin/epm
cp lang/runtime/el_runtime.c dist/sdk/runtime/
cp lang/runtime/el_runtime.h dist/sdk/runtime/
cp lang/runtime/engram_store.c dist/sdk/runtime/
cp lang/runtime/engram_store.h dist/sdk/runtime/
# Ship the WHOLE runtime link set, not el_runtime.c alone. el_runtime.c
# #includes six engram headers and calls into all six sibling .c files,
# so an SDK carrying only el_runtime.c{,.h} + engram_store.c{,.h} cannot
# link — downstream `ld` fails on engram_ground_json, eg_find_relation,
# cog_assert_two_axis and friends. lang/runtime/SOURCES is the source of
# truth; --check makes a missing file fail the release loudly.
for f in $(scripts/el-runtime-sources.sh --check) \
$(scripts/el-runtime-sources.sh --headers --check); do
cp "lang/runtime/${f}" dist/sdk/runtime/
done
cp lang/runtime/SOURCES dist/sdk/runtime/
cp lang/runtime/*.el dist/sdk/runtime/
tar -czf dist/el-sdk-latest.tar.gz -C dist/sdk .
echo "SDK tarball bundled: dist/el-sdk-latest.tar.gz"
@@ -274,12 +291,16 @@ jobs:
"${GITEA_API}/repos/${REPO}/releases/${RELEASE_ID}/assets"
}
# Per-file assets (downstream CI needs these individually)
# Per-file assets (downstream CI needs these individually).
# lang/install.sh downloads every one of these by name — the list is
# lang/runtime/SOURCES. Shipping el_runtime.c alone produced a lib/
# that could not link; that is the bug this loop closes.
upload_asset lang/dist/platform/elc elc
upload_asset lang/runtime/el_runtime.c el_runtime.c
upload_asset lang/runtime/el_runtime.h el_runtime.h
upload_asset lang/runtime/engram_store.c engram_store.c
upload_asset lang/runtime/engram_store.h engram_store.h
for f in $(scripts/el-runtime-sources.sh --check) \
$(scripts/el-runtime-sources.sh --headers --check); do
upload_asset "lang/runtime/${f}" "${f}"
done
upload_asset lang/runtime/SOURCES SOURCES
# SDK bundle and installer binary
upload_asset dist/el-sdk-latest.tar.gz el-sdk-latest.tar.gz
@@ -350,6 +371,26 @@ jobs:
--version="${VERSION}" \
--source=runtime/el_runtime.js
# el-runtime-src — the COMPLETE runtime link set as one tarball.
#
# The el-runtime-c / el-runtime-h packages above are single files and are
# kept for backward compatibility with consumers that already pull them,
# but they are NOT sufficient to link: el_runtime.c calls into six engram
# sibling translation units. New consumers should pull el-runtime-src and
# link everything named in its SOURCES file.
tar -czf /tmp/el-runtime-src.tar.gz \
-C runtime SOURCES \
$(../scripts/el-runtime-sources.sh --check) \
$(../scripts/el-runtime-sources.sh --headers --check)
gcloud artifacts generic upload \
--repository=foundation-prod \
--location=us-central1 \
--project=neuron-785695 \
--package=el-runtime-src \
--version="${VERSION}" \
--source=/tmp/el-runtime-src.tar.gz
echo "Published El SDK version=${VERSION} to foundation-prod"
# Keep key alive for the ci-base rebuild step below
# (deleted in that step after docker push)
@@ -386,8 +427,9 @@ jobs:
FROM ${BASE}
COPY dist/platform/elc /opt/el/dist/platform/elc
COPY dist/bin/elb /opt/el/dist/bin/elb
COPY runtime/el_runtime.c /opt/el/runtime/el_runtime.c
COPY runtime/el_runtime.h /opt/el/runtime/el_runtime.h
# Whole runtime link set — el_runtime.c alone does not link (it calls
# into the six engram sibling TUs). See lang/runtime/SOURCES.
COPY runtime/ /opt/el/runtime/
COPY runtime/el_runtime.js /opt/el/runtime/el_runtime.js
RUN chmod +x /opt/el/dist/platform/elc /opt/el/dist/bin/elb
EOF
+42 -3
View File
@@ -9,13 +9,52 @@ LANG_DIR="$ROOT/lang"
RUNTIME="$LANG_DIR/runtime"
ELC="$LANG_DIR/dist/platform/elc"
# Runtime guards — catch drift and growth before they are committed, not in CI.
# check-single-runtime.sh : el_runtime.c must not be FORKED (a lagging copy
# shipped to prod and dropped learned hebb edges).
# check-runtime-growth.sh : el_runtime.c must not GROW (it is a 2026-05-03
# build shim that was never retired; see BUDGET).
echo "→ Runtime guards..."
bash "$ROOT/scripts/check-single-runtime.sh"
bash "$ROOT/scripts/check-runtime-growth.sh"
# If elc isn't built yet, skip with a warning rather than blocking
if [ ! -x "$ELC" ]; then
echo "⚠ elc not found at lang/dist/platform/elc — skipping pre-commit tests"
echo " Build it first: cd lang && gcc -O2 -I runtime dist/elc-bootstrap.c runtime/el_runtime.c -lcurl -lpthread -o dist/elc-gen2 && ./dist/elc-gen2 el-compiler/src/compiler.el > /tmp/elc.c && gcc -O2 -I runtime /tmp/elc.c runtime/el_runtime.c -lcurl -lpthread -o dist/platform/elc"
echo " Build it first: see 'Rebuilding the Compiler' in lang/AGENTS.md"
echo " (link \$($ROOT/scripts/el-runtime-sources.sh $RUNTIME) — NOT el_runtime.c alone)"
exit 0
fi
# The runtime is MULTI-FILE (lang/runtime/SOURCES). This hook used to link
# "$RUNTIME/el_runtime.c" alone with stderr sent to /dev/null — so once
# el_runtime.c started calling into the engram siblings, every native test
# reported as FAILED with the real `ld` error invisible. Build the whole set
# once into an archive, then link each test against it.
# macOS: Homebrew openssl@3 is not on the default include/lib search path, so
# without these the link fails on -lssl/-lcrypto. Empty on Linux/CI.
SSL_INC=""
SSL_LIB=""
if command -v brew >/dev/null 2>&1 && OSSL="$(brew --prefix openssl@3 2>/dev/null)" && [ -n "$OSSL" ]; then
SSL_INC="-I$OSSL/include"
SSL_LIB="-L$OSSL/lib"
fi
echo "→ Building runtime (compile-once, link-many)..."
HOOK_LIB="/tmp/el_hook_libel.a"
HOOK_OBJ="/tmp/el_hook_obj"
rm -rf "$HOOK_OBJ" && mkdir -p "$HOOK_OBJ"
if ! for src in $("$ROOT/scripts/el-runtime-sources.sh" --check "$RUNTIME"); do
gcc -O2 -c -I "$RUNTIME" $SSL_INC "$src" -o "$HOOK_OBJ/$(basename "${src%.c}").o" || exit 1
done; then
echo "✗ Pre-commit failed: the runtime does not compile."
echo " Re-run without 2>/dev/null to see the error:"
echo " gcc -O2 -c -I $RUNTIME \$($ROOT/scripts/el-runtime-sources.sh $RUNTIME)"
exit 1
fi
ar rcs "$HOOK_LIB" "$HOOK_OBJ"/*.o
echo "→ Running El native tests..."
PASS=0
FAIL=0
@@ -27,8 +66,8 @@ for test_file in "$LANG_DIR"/tests/native/test_*.el; do
tmp_bin="/tmp/el_hook_${name}"
if "$ELC" --test "$test_file" > "$tmp_c" 2>/dev/null \
&& gcc -O2 -I "$RUNTIME" "$tmp_c" "$RUNTIME/el_runtime.c" \
-lcurl -lpthread -lm -o "$tmp_bin" 2>/dev/null \
&& gcc -O2 -I "$RUNTIME" $SSL_INC $SSL_LIB "$tmp_c" "$HOOK_LIB" \
-lcurl -lssl -lcrypto -lpthread -lm -o "$tmp_bin" 2>/dev/null \
&& "$tmp_bin" 2>/dev/null; then
PASS=$((PASS + 1))
else
+26 -6
View File
@@ -199,21 +199,35 @@ wrong, say so with a measurement rather than editing it.
All build/test commands run from `lang/` unless noted. Grounded in `.gitea/workflows/sdk-release.yaml`, `lang/install.sh`, and `lang/AGENTS.md`.
> ### The runtime is MULTI-FILE — never link `el_runtime.c` alone
>
> `lang/runtime/el_runtime.c` `#include`s six engram headers and makes hard cross-TU calls into all six sibling `.c` files. **Linking it by itself fails at `ld`** (undefined `engram_ground_json`, `engram_activate_inner`, `eg_find_relation`, `cog_assert_two_axis`, …). The canonical link set lives in exactly one place — **`lang/runtime/SOURCES`** — and is printed by `scripts/el-runtime-sources.sh`:
>
> ```bash
> scripts/el-runtime-sources.sh lang/runtime # ten .c files, in link order
> ```
>
> Use `$(scripts/el-runtime-sources.sh <runtime-dir>)` in every link line. Do not spell the list out longhand — it was written out in ~8 places, every copy drifted, and that is why the one-file link line below shipped broken for months. *(Corrected 2026-08-16.)*
**Self-host the compiler** (seed binary → gen2 elc):
```bash
cd lang
dist/platform/elc-linux-amd64 elc-cli.el > dist/elc-gen2.c # seed is the committed linux-amd64 binary
gcc -O2 -I el-compiler/runtime dist/elc-gen2.c \
el-compiler/runtime/el_runtime.c \
gcc -O2 -I runtime dist/elc-gen2.c \
$(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm \
-o dist/platform/elc
```
On macOS/arm64 the canonical local binary is `dist/platform/elc`; verify self-hosting by recompiling and `diff`ing the emitted `.c` (see `lang/AGENTS.md`). Note: `lang/AGENTS.md` says `el_seed.c` supersedes `el_runtime.c`, but the release workflow still links `el_runtime.c`/`.h` — treat `el_runtime.c` as the published runtime; reconcile which is canonical **(verify)**.
On macOS/arm64 the canonical local binary is `dist/platform/elc`; verify self-hosting by recompiling and `diff`ing the emitted `.c` (see `lang/AGENTS.md`).
*(Corrected 2026-08-16: this recipe compiled `el-compiler/runtime/el_runtime.c`. That path is a **lagging fork** — the "DO NOT EDIT" list at the top of this file names it as such. Building the canonical compiler from a known-stale fork was a live defect. It now uses `lang/runtime/`, the canonical source.)*
**Which runtime file is canonical — resolved.** *(This note previously read "`lang/AGENTS.md` says `el_seed.c` supersedes `el_runtime.c`, but the release workflow still links `el_runtime.c`/`.h` — reconcile which is canonical **(verify)**." It is now reconciled.)* **Neither supersedes the other; both ship, together with eight more.** `el_runtime.c` was created on 2026-05-03 as an explicitly temporary build shim — deleted that afternoon, restored 25 minutes later "UNTIL the compiler is updated to emit `#include el_seed.h`" — and the `until` never happened, so it grew to 20.5k lines. The end state remains a seed-only boundary (`elc` emitting `#include "el_seed.h"`, `elb` dropping its hardcoded runtime path); until that lands, **the canonical unit is the set in `lang/runtime/SOURCES`, not any one file.**
**Build `elb`** (build coordinator, the `.NET`-style incremental linker — compiles each module independently, no monolithic blobs):
```bash
dist/platform/elc elb.el > dist/elb.c
gcc -O2 -I el-compiler/runtime dist/elb.c el-compiler/runtime/el_runtime.c \
gcc -O2 -I runtime dist/elb.c $(../scripts/el-runtime-sources.sh runtime) \
-lcurl -lssl -lcrypto -lpthread -lm -o dist/bin/elb
```
`epm` and `el-install` are then built via `elb --clean --elc=… --runtime=… --out=…`.
@@ -221,10 +235,16 @@ gcc -O2 -I el-compiler/runtime dist/elb.c el-compiler/runtime/el_runtime.c \
**Compile + run an El program:**
```bash
elc src/app.el > dist/app.c
cc -std=c11 -O2 -I <lib>/el_runtime -o dist/app dist/app.c <lib>/el_runtime.c -lcurl -lpthread
cc -std=c11 -O2 -I <lib> -o dist/app dist/app.c \
<lib>/el_runtime.c <lib>/el_seed.c \
<lib>/engram_store.c <lib>/engram_vindex.c <lib>/engram_geometry.c \
<lib>/engram_reason.c <lib>/engram_verify.c <lib>/engram_cognition.c \
<lib>/eg_cosine_batch.c <lib>/eg_cosine_batch_strategy_cpu.c \
-lcurl -lssl -lcrypto -lpthread -lm
```
(Inside this repo, replace the file list with `$(scripts/el-runtime-sources.sh lang/runtime)`. `install.sh` installs all of these into `<lib>`.)
**Tests** — shell suites `bash tests/{text,calendar,time,html_sanitizer}/run.sh` (with `ELC=$(pwd)/dist/platform/elc EL_HOME=$(pwd)`), plus native suites via `elc --test tests/native/test_*.el` (core, text, string, math, state, time, json, env, fs) compiled and run against `el_runtime.c`.
**Tests** — shell suites `bash tests/{text,calendar,time,html_sanitizer}/run.sh` (with `ELC=$(pwd)/dist/platform/elc EL_HOME=$(pwd)`), plus native suites via `elc --test tests/native/test_*.el` (core, text, string, math, state, time, json, env, fs) compiled and run against the full runtime set.
**Publishing — how downstream gets the SDK.** On push to `main`, `sdk-release.yaml`:
1. Publishes a Gitea `latest` release with per-file assets `elc`, `el_runtime.c`, `el_runtime.h`, the SDK tarball, and `el-install`.
+7 -3
View File
@@ -548,9 +548,13 @@ before `main` does anything. That is the dividend of discovery-precedes-executio
```
# once, ever (or when the runtime/framework changes):
cc -c el_runtime.c -o el_runtime.o
elc eltest.el > eltest.c && cc -c eltest.c -o eltest.o
ar rcs libeltest.a el_runtime.o eltest.o
# The runtime is MULTI-FILE — compile every .c named in lang/runtime/SOURCES.
# Linking el_runtime.c alone fails: it calls into the six engram sibling TUs.
for src in $(scripts/el-runtime-sources.sh lang/runtime); do
cc -c "$src" -o "obj/$(basename "${src%.c}").o"
done
elc eltest.el > eltest.c && cc -c eltest.c -o obj/eltest.o
ar rcs libeltest.a obj/*.o
# per suite:
elc --test foo_test.el > foo_test.c # registry + bodies only
+54 -25
View File
@@ -13,7 +13,7 @@
// relations add edges. Every node enters with PROVENANCE + grounding-level
// + stewardship class from the moment of entry.
//
// transduce_manifold() is THE single mechanism one function, polymorphic, with no
// transduce_bytes() is THE single mechanism one function, polymorphic, with no
// content-type branch inside it. It does not ask whether a payload is
// prose, structured data, or raw/opaque bytes (audio, or anything else);
// it runs one boundary-scan-with-fixed-window-fallback chunking algorithm
@@ -401,25 +401,54 @@ fn head80(s: String) -> String {
// truncates at the first embedded NUL, which is routine in real binary
// bytes) is a MECHANICAL fidelity concern that belongs to whatever produced
// `source` (see ingest_file's file_source_string below) not a
// content-type judgment made in here. transduce_manifold() never learns whether a
// content-type judgment made in here. transduce_bytes() never learns whether a
// chunk is plain text or a base64-encoded raw-byte window; every chunk is
// handled identically either way.
// RENAMED transduce -> transduce_manifold (2026-08-16). Two reasons, and the
// first is not the interesting one:
// NAMING, CORRECTED 2026-08-16 (second pass). This function was renamed
// `transduce` -> `transduce_bytes` earlier the same day, on the reasoning
// that it "was never signal->geometry — it chunks already-extracted content
// and PACKS it into a node+edge manifold, one layer up, and it had taken the
// name that belongs to the primitive underneath it."
//
// 1. Mechanical: `transduce` is now a LANGUAGE primitive in el_runtime.h
// (transduce(signal, modality) -> Geometry). Every El `fn name(...)`
// compiles to a global C symbol with that exact name, so keeping this
// name here is a hard `conflicting types for 'transduce'` compile error
// the moment ingest.c links el_runtime.c. Measured, not anticipated.
// THAT REASONING WAS BACKWARDS, and it is worth recording why rather than
// quietly re-renaming. Producing a node+edge manifold is not a layer above
// transduction it IS transduction. Transduction is not conversion. When you
// take in music you do not store the song as one discrete geometry; you break
// it into its component parts and store the geometry of each along with the
// relations between them. The song is the structure of those relations.
// Signal -> one vector is the operation UNDERNEATH transduction, and its name
// is encoding, or geometry. So the layer that was doing it right got renamed
// out of the way so the layer doing it wrong could have the name.
//
// 2. Actual: this function was never signal->geometry. It chunks already-
// extracted content and PACKS it into a node+edge manifold a real
// operation, but one layer up, and it had taken the name that belongs to
// the primitive underneath it. `transduce` is where a signal becomes
// geometry; `transduce_manifold` is where extracted content becomes
// structure. Nothing about this function's behaviour changed.
fn transduce_manifold(nodes: [String], edges: [String], source: String,
// The primitive has since been corrected: `transduce(signal, modality)` now
// returns a Manifold components plus relations not a Geometry
// (el_runtime.c, "Manifold"). The two layers are therefore doing the SAME KIND
// of thing, and the inversion dissolves rather than needing to be re-argued.
//
// What is left is a real distinction, and it is about MODALITY, not layering:
//
// * `transduce(signal, modality)` dispatches to a realizer that KNOWS the
// modality and can name its components for audio: pitch, interval,
// rhythm, harmonic function.
// * `transduce_bytes` below is the OPAQUE-BYTES realizer: the decomposition
// available to a reader that knows nothing about what it is reading. It
// still yields components and relations (chunk nodes; contains / precedes
// / section_of edges), which is why it is transduction and not packing. It
// just cuts on the only structure visible without understanding byte
// boundaries so its components are positional rather than meaningful.
// That is a LIMITATION of this realizer, not the definition of the
// operation.
//
// The name is suffixed by its modality, not demoted to a lesser layer. Keeping
// a distinct symbol is also still mechanically required: every El `fn name`
// compiles to a global C symbol, so reusing `transduce` here is a hard
// `conflicting types` error the moment ingest.c links el_runtime.c.
//
// WHERE THIS SHOULD GO: this function should become a registered realizer
// returning a real Manifold, so ingest rides the same primitive as every other
// modality instead of carrying a parallel implementation. Not done here.
// Nothing about this function's behaviour changed in this pass.
fn transduce_bytes(nodes: [String], edges: [String], source: String,
prov: String, ground: String, steward: String,
root_lid: String, root_title: String) -> [String] {
let tagbase: String = "prov:" + prov + " ground:" + ground + " steward:" + steward
@@ -546,8 +575,8 @@ fn default_steward() -> String {
// trustworthy verbatim. When they don't (silent truncation happened),
// rebuild the payload as base64-encoded fixed-size windows read directly
// off disk (fs_read_b64_chunk binary-safe in C), joined with the same
// "\n\n" boundary marker transduce_manifold()'s generic scan already looks for, so
// transduce_manifold() sees one ordinary boundary-delimited payload and runs its one
// "\n\n" boundary marker transduce_bytes()'s generic scan already looks for, so
// transduce_bytes() sees one ordinary boundary-delimited payload and runs its one
// algorithm on it exactly as it would on prose it never learns that a
// fidelity problem occurred upstream, let alone why.
fn file_source_string(path: String, text: String, real_size: Int) -> String {
@@ -556,7 +585,7 @@ fn file_source_string(path: String, text: String, real_size: Int) -> String {
// 3072 raw bytes -> 4096 base64 chars (3 divides evenly into base64's
// 3-byte/4-char ratio); keeps each resulting node's content a clean,
// bounded, low-kilobytes unit, same order of magnitude as the fixed
// fallback window in transduce_manifold() itself.
// fallback window in transduce_bytes() itself.
let win: Int = 3072
let out: String = ""
let off: Int = 0
@@ -576,7 +605,7 @@ fn file_source_string(path: String, text: String, real_size: Int) -> String {
}
// ingest one file -> report JSON. Uniform for every file regardless of
// extension or content transduce_manifold() decides nothing about content-type, so
// extension or content transduce_bytes() decides nothing about content-type, so
// neither does this function; it only decides whether the raw bytes made it
// through the read intact (file_source_string), which is a fidelity
// question, not a format one.
@@ -588,14 +617,14 @@ fn ingest_file(path: String) -> String {
return "{\"error\":\"empty or unreadable\",\"path\":" + j_q(path) + "}"
}
let prov: String = "file:" + path
let packed: [String] = transduce_manifold(el_list_empty(), el_list_empty(),
let packed: [String] = transduce_bytes(el_list_empty(), el_list_empty(),
source, prov, default_ground(), default_steward(),
"doc:" + basename(path), basename(path))
return merge_packed(packed)
}
// ingest a directory: walk one level, ingest every file found, aggregate.
// No extension filter transduce_manifold() handles any payload uniformly now, so
// No extension filter transduce_bytes() handles any payload uniformly now, so
// there is no content-type gate at the directory boundary either.
fn ingest_dir(path: String) -> String {
let entries: [String] = fs_list(path)
@@ -630,7 +659,7 @@ fn ingest_dir(path: String) -> String {
fn ingest_url(url: String) -> String {
let body: String = http_get(url)
if str_eq(body, "") { return "{\"error\":\"empty fetch\",\"url\":" + j_q(url) + "}" }
let packed: [String] = transduce_manifold(el_list_empty(), el_list_empty(),
let packed: [String] = transduce_bytes(el_list_empty(), el_list_empty(),
body, "url:" + url, "extracted", "public-web",
"url:" + url, url)
return merge_packed(packed)
@@ -645,7 +674,7 @@ fn ingest_llm(query: String) -> String {
let resp: String = http_post_json("http://127.0.0.1:11434/api/generate", body)
let answer: String = json_get_string(resp, "response")
if str_eq(answer, "") { return "{\"error\":\"no model response\"}" }
let packed: [String] = transduce_manifold(el_list_empty(), el_list_empty(),
let packed: [String] = transduce_bytes(el_list_empty(), el_list_empty(),
answer, "llm:" + model + ":" + query, "candidate-provisional", "guide-provisional",
"llm:" + query, "guide answer: " + query)
return merge_packed(packed)
@@ -697,7 +726,7 @@ fn ingest_stream(path: String) -> String {
// It is NOT a content-type flag: it says nothing about what's inside the
// bytes once fetched, and none of the five ingest_* functions it selects
// among interpret their payload differently by content shape anymore
// they all hand off to the single, format-agnostic transduce_manifold(). The old
// they all hand off to the single, format-agnostic transduce_bytes(). The old
// "structured" value (a caller-declared alias for "file", used only to hint
// the now-removed JSON-vs-prose branch) is gone along with that branch.
let kind: String = env("INGEST_KIND")
+23 -5
View File
@@ -77,14 +77,30 @@ This is where almost all work belongs. El programs are source files that get com
This is the self-contained C OS-boundary layer. It provides the `__`-prefixed primitives that compiled El programs call: libcurl HTTP, pthreads, filesystem I/O, arena allocation, etc. It is **not generated** — it is maintained by hand.
The runtime is native El (`runtime/*.el`) over a C OS-boundary. **Status (verified 2026-08-15):** the migration to a seed-only boundary is *in progress, not done*. Two files exist:
- `runtime/el_runtime.c` (~860 KB) — **LIVE**. Holds the engram store (`EngramStore engram_global`) plus the `http_*`/`json_*`/`state_*`/`engram_*` impls. It is the authoritative single-file link target for the compiler, and `tools/install.sh` compiles it into `libel.a`. This is where a new C builtin's *implementation* must currently live to be linkable.
- `runtime/el_seed.c` — the intended hand-maintained `__`-prefixed seed (thin wrappers over the above). It is compiled alongside `el_runtime.c` by `tools/install.sh`, but does **not** compile standalone yet (see the build-path caveat under "Rebuilding the Compiler").
The runtime is native El (`runtime/*.el`) over a C OS-boundary. **Status (verified 2026-08-16):** the migration to a seed-only boundary is *in progress, not done*.
**The runtime is MULTI-FILE. There is no single-file link target and there has not been one for months.** The canonical link set is listed once, in **`runtime/SOURCES`**, and printed by `scripts/el-runtime-sources.sh`. It currently holds ten translation units: `el_runtime.c`, `el_seed.c`, the six `engram_*.c` concern files, and `eg_cosine_batch{,_strategy_cpu}.c`.
- `runtime/el_runtime.c` (~940 KB, 20.5k lines) — **LIVE, and oversized.** It began life on 2026-05-03 as a temporary build shim: it was deleted that afternoon ("runtime is 100% native El") and restored 25 minutes later, explicitly "UNTIL the compiler is updated to emit `#include el_seed.h`". That `until` never arrived, and in the 3.5 months since, the file doubled. **It is not a volatility unit — it is a dumping ground.** ~47.5% of it is engram code that belongs in the six sibling files that already exist. Do not add to it. See "Where a new C builtin goes" below.
- `runtime/el_seed.c` — the intended hand-maintained `__`-prefixed seed (thin wrappers over the above).
- `runtime/engram_{store,vindex,geometry,reason,verify,cognition}.c` — the engram concerns, each with its own header. `el_runtime.c` `#include`s all six headers and makes hard cross-TU calls into all six.
> **Linking `el_runtime.c` alone does not work and has not for months.** It fails at `ld` with undefined symbols (`engram_ground_json`, `engram_activate_inner`, `eg_find_relation`, `cog_assert_two_axis`, …). Any recipe, script, or CI step that names `el_runtime.c` by itself is stale — replace it with `$(scripts/el-runtime-sources.sh lang/runtime)`.
**Only edit these when you genuinely need OS-level access** (raw sockets, GPU calls, new libcurl features, a new engram store op). For everything else, write El.
#### Where a new C builtin goes
**Put it in the `.c` that owns the concern — NOT in `el_runtime.c`.**
*Placement is a link-time concern. The compiler cannot tell which `.c` a symbol came from, and never could.* `builtin_arity` in `el-compiler/src/codegen.el` maps NAME → ARITY INT and nothing else (~413 entries); the El name is emitted as the exact C symbol and resolved by `ld`. Proof, if you want it: `nm lang/dist/platform/elc` on the *shipped* compiler shows `T _engram_geo_reify_index_new` (defined in `engram_geometry.c`), `T _vindex_insert` (`engram_vindex.c`), `T _engram_think` (`engram_cognition.c`), `T _engram_reason_abduce` (`engram_reason.c`). **The shipped compiler is already linked from ten translation units.** A builtin defined in a sibling `.c` is exactly as linkable as one defined in `el_runtime.c`.
Choose the file by concern: engram store ops → `engram_store.c`; index → `engram_vindex.c`; geometry/priming → `engram_geometry.c`; reasoning → `engram_reason.c`; grounding/consistency → `engram_verify.c`; think/stance → `engram_cognition.c`. **If no existing file owns it, create one** — add the `.c` to `runtime/SOURCES` (one line) and every build path picks it up. For a builtin that belongs to a downstream program rather than the runtime, declare `c_source "path/to/file.c"` in that program's `manifest.el`; `elb` already links it (`parse_manifest_c_sources`, `lang/elb.el:82`).
> **`el_runtime.c` is on a ratchet and will reject your commit.** `runtime/BUDGET` caps it at its current line count *with no headroom*, and separately caps the number of `engram_*`/`eg_*`/`cog_*` function definitions in it. `scripts/check-runtime-growth.sh` enforces both in CI and in `.githooks/pre-commit`. **The numbers may only ever go down — do not raise them.** Every other runtime file is deliberately uncapped, because that is where the code is supposed to go. When you move code *out*, lower the numbers in the same commit; the guard tells you the new values.
When you add a C builtin (verbatim-emit recipe — the El name is emitted as the exact C symbol; `builtin_arity` is an arity guard only, not a dispatch table):
1. Implement the C function in `el_runtime.c` (and declare it in `el_runtime.h`).
1. Implement the C function in the **concern-owning `.c`** (and declare it in that file's `.h`). Add the file to `runtime/SOURCES` if it is new. Only put it in `el_runtime.c` if it is genuinely EL core (val/str/map/list/arena) — that is ~8% of what is in there today.
2. Add a `__`-prefixed thin wrapper in `el_seed.c` and declare it in `el_seed.h`.
3. Add the name to `builtin_arity` in `el-compiler/src/codegen.el` — add **both** the plain and `__`-prefixed spellings.
4. Rebuild the elc binary (see below) and confirm the self-host fixpoint is byte-identical.
@@ -125,7 +141,9 @@ diff elc-new.c elc-verify.c # must be identical
mv dist/platform/elc-new dist/platform/elc
```
> **Build-path caveat (verified 2026-08-15).** `el_seed.c` is the intended hand-maintained OS-boundary seed, but it does **not** compile standalone under modern clang: it wraps ~16 unprefixed `el_runtime.c` symbols (`http_serve`, `json_*`, `state_*`, `http_response`) without prototypes, and clang treats implicit declarations as errors (C99+). The productionised install (`tools/install.sh`) builds `libel.a` from **both** `el_seed.o` + `el_runtime.o` together, which is why linking succeeds there. To make `el_seed.c` build on its own, add prototypes for those symbols (or `#include "el_runtime.h"`, reconciling the `__http_serve` return-type mismatch first). Until then, `el_runtime.c` is the authoritative single-file link target for the compiler.
> **Build-path caveat (verified 2026-08-15).** `el_seed.c` is the intended hand-maintained OS-boundary seed, but it does **not** compile standalone under modern clang: it wraps ~16 unprefixed `el_runtime.c` symbols (`http_serve`, `json_*`, `state_*`, `http_response`) without prototypes, and clang treats implicit declarations as errors (C99+). The productionised install (`tools/install.sh`) builds `libel.a` from **both** `el_seed.o` + `el_runtime.o` together, which is why linking succeeds there. To make `el_seed.c` build on its own, add prototypes for those symbols (or `#include "el_runtime.h"`, reconciling the `__http_serve` return-type mismatch first).
>
> **There is no single-file link target.** *(Corrected 2026-08-16 — this paragraph previously ended "`el_runtime.c` is the authoritative single-file link target for the compiler". Measured: that is false. Linking `elc-new.c` against `runtime/el_runtime.c` alone fails at `ld` with undefined `engram_ground_json`, `engram_activate_inner`, `eg_find_relation`, `cog_assert_two_axis`, and others, because `el_runtime.c` `#include`s six engram headers and calls into all six sibling `.c` files.)* Link the set in `runtime/SOURCES` via `$(../scripts/el-runtime-sources.sh runtime)`.
After changing `el_seed.c` only (no El source changes), rebuild downstream programs but do NOT need to rebuild the compiler binary itself — the seed is linked at the application level, not the compiler level.
+183 -168
View File
@@ -1,67 +1,33 @@
// transduce.el geometry as a first-class El value, and a realizer written
// in El. Runnable: this is the worked example for the transduce surface, and
// it doubles as an executable proof because it checks every claim it makes.
// transduce.el transduction decomposes a signal into components and the
// relations between them. Runnable: this is the worked example for the
// transduce surface, and it exits non-zero if any claim in it stops being true.
//
// elc lang/examples/transduce.el > transduce.c
// cc -std=c11 -O2 -I lang/runtime -o transduce transduce.c \
// lang/runtime/el_runtime.c lang/runtime/el_seed.c \
// lang/runtime/engram_*.c -lcurl -lpthread -lm
// lang/runtime/el_runtime.c lang/runtime/el_seed.c \
// lang/runtime/engram_store.c lang/runtime/engram_vindex.c \
// lang/runtime/engram_cognition.c lang/runtime/engram_geometry.c \
// lang/runtime/engram_reason.c lang/runtime/engram_verify.c \
// -lcurl -lpthread -lm
// ./transduce # exits 0 only if every check passes
//
// (A `test "..."` form of the same checks lives in
// lang/tests/native/test_transduce.el, for when the native harness is
// repaired the shipped elc currently emits calls to __el_reg_count and
// friends without emitting their definitions, which breaks every native test
// equally, test_math.el included. Verified 2026-08-16, unrelated to this work.)
// It writes to an IN-MEMORY engram (leave ENGRAM_STORE unset) and contacts no
// server. The same claims are asserted by the native harness in
// lang/tests/native/test_transduce.el.
//
// WHY THIS EXISTS. Until 2026-08-16 no El ingest path could carry a vector:
// nodes took text, and geometry was DERIVED from that text. Text was the
// mandatory entry medium, so any non-text modality had to be DESCRIBED in
// prose first and the geometry we reasoned over was the geometry OF THE
// DESCRIPTION, not of the signal. Two things fix that, and both are shown
// below: geometry is a VALUE that carries its own width, and a REALIZER is an
// ordinary El function so admitting a new modality never requires a runtime
// patch.
// WHAT CHANGED, AND WHY IT MATTERS. #144 shipped
// `transduce(signal, modality) -> Geometry`: one vector per signal. That made
// transduction a CONVERSION take a thing, encode it, store a position and
// what a conversion returns is a fingerprint. A fingerprint can be matched and
// ranked, and that is all it can ever do. It cannot be decomposed, cannot have
// one part grounded while another is not, and cannot be contradicted in one
// part while holding in another, because it has no parts.
//
// COMPARISON DISCIPLINE (measured, not stylistic): elc lowers `a == b`
// numerically only when both operand NAMES are in the per-function int-name
// set that `let x: Int` populates. A bare `f(x) == 0` is not a registered
// name and lowers to str_eq strcmp on two integers as pointers. `<` and `>`
// lower directly with no inference, so truthiness is written `> 0` / `< 1`.
// A song is not a point. It decomposes into pitch, interval, rhythm, harmonic
// function components, each with its own geometry, plus the relations among
// them. THE SONG IS THE STRUCTURE OF THE RELATIONS. transduce now returns a
// Manifold, and a realizer's job is to say what its modality's components ARE.
// A realizer, written entirely in El
// Not in the runtime. Not known to the compiler. Registered by NAME and
// dispatched to through transduce(). That is the whole claim.
fn tone_realizer(signal: String) -> Geometry {
let g: Geometry = geometry_new(4)
let n: Int = str_len(signal)
let a: Int = geometry_set(g, 0, int_to_float(n))
let b: Int = geometry_set(g, 1, int_to_float(n * 2))
let c: Int = geometry_set(g, 2, int_to_float(n * 3))
let d: Int = geometry_set(g, 3, int_to_float(n * 4))
g
}
// A second modality, to show the registry keys on modality rather than just
// returning whatever was registered last.
fn pulse_realizer(signal: String) -> Geometry {
let g: Geometry = geometry_new(2)
let a: Int = geometry_set(g, 0, 1.0)
let b: Int = geometry_set(g, 1, 0.0)
g
}
// A deliberately BROKEN realizer: returns something that is not a Geometry.
fn bogus_realizer(signal: String) -> Geometry {
return 12345
}
// Fails FAST rather than accumulating a count, for a measured reason: a first
// cut wrote `let fails: Int = fails + check(...)` and `+` lowered to STRING
// CONCAT, because elc dispatches `+` on whether both operands are known-Int and
// a user-defined fn call is not so the counter printed 4343632752, a pointer.
// Nothing was wrong with the checks; the tally was lying. Exiting at the first
// failure needs no arithmetic at all, so there is nothing left to get wrong.
fn check(ok: Int, label: String) -> Int {
if ok > 0 {
println(" ok " + label)
@@ -84,128 +50,177 @@ fn eq_int(a: Int, b: Int) -> Int {
return 0
}
// A DECOMPOSING realizer, written entirely in El
// "tone" signals are note letters, e.g. "CEG". This does NOT return one vector
// for the chord. It returns the PARTS one component per note, one per
// interval between adjacent notes and the relations that make those parts a
// chord rather than an unordered bag of pitches.
//
// The interval is deliberately a COMPONENT, not a field on a note. An interval
// is a thing with its own geometry belonging to neither endpoint; modelling it
// as an attribute of one of them is the same collapse, one level down.
fn tone_realizer(signal: String) -> Manifold {
let m: Manifold = manifold_new()
let n: Int = str_len(signal)
let i: Int = 0
while i < n {
let code: Int = str_char_code(signal, i)
let g: Geometry = geometry_new(2)
let s0: Int = geometry_set(g, 0, int_to_float(code))
let s1: Int = geometry_set(g, 1, int_to_float(i))
let idx: Int = manifold_add(m, "note:" + int_to_str(i), "pitch", g)
let f: Int = geometry_free(g)
i = i + 1
}
let j: Int = 1
while j < n {
let a: Int = str_char_code(signal, j - 1)
let b: Int = str_char_code(signal, j)
let lo: String = "note:" + int_to_str(j - 1)
let hi: String = "note:" + int_to_str(j)
let key: String = "interval:" + int_to_str(j - 1) + "-" + int_to_str(j)
let g: Geometry = geometry_new(1)
let s: Int = geometry_set(g, 0, int_to_float(b - a))
let idx: Int = manifold_add(m, key, "interval", g)
let f: Int = geometry_free(g)
let e1: Int = manifold_relate(m, key, "spans", lo, 0.9)
let e2: Int = manifold_relate(m, key, "spans", hi, 0.9)
let e3: Int = manifold_relate(m, lo, "sounds_before", hi, 0.8)
j = j + 1
}
m
}
// #144's contract, kept as a control: one vector for the whole signal.
fn fingerprint_realizer(signal: String) -> Geometry {
let g: Geometry = geometry_new(4)
let n: Int = str_len(signal)
let a: Int = geometry_set(g, 0, int_to_float(n))
g
}
fn main() -> Void {
println("geometry is a value that carries its own width")
let g8: Geometry = geometry_new(8)
let _c: Int = check(geometry_is(g8), "geometry_new returns a live Geometry")
let d8: Int = geometry_dim(g8)
let _c: Int = check(eq_int(d8, 8), "a Geometry carries its own width (8)")
let _c: Int = check(geometry_free(g8), "geometry_free reports what it did")
println("nonsense is refused — with no arbitrary max-dim bound")
// #141 needed `dim <= 8192` only to bound an allocation sized from a
// caller's CLAIM about a string's length. A value that carries its own
// width has nothing left to validate.
let z: Geometry = geometry_new(0)
let zi: Int = geometry_is(z)
let _c: Int = check(1 - zi, "dim 0 is not a geometry")
let ng: Geometry = geometry_new(-4)
let ngi: Int = geometry_is(ng)
let _c: Int = check(1 - ngi, "negative dim is not a geometry")
let nd: Int = geometry_dim(0)
let _c: Int = check(1 - nd, "geometry_dim of a non-geometry is 0, not a crash")
let nf: Int = geometry_free(0)
let _c: Int = check(1 - nf, "geometry_free of a non-geometry is a no-op")
println("components round-trip, and out-of-range is refused")
let g3: Geometry = geometry_new(3)
let s0: Int = geometry_set(g3, 0, 1.5)
let s1: Int = geometry_set(g3, 1, -2.5)
let _c: Int = check(s0, "set in range succeeds")
let oob: Int = geometry_set(g3, 3, 9.0)
let _c: Int = check(1 - oob, "set out of range is refused, not silently dropped")
let _c: Int = check(near(geometry_get(g3, 0), 1.5), "component 0 round-trips")
let _c: Int = check(near(geometry_get(g3, 1), -2.5), "component 1 round-trips (negative)")
let ff3: Int = geometry_free(g3)
println("hex is an EDGE adapter, and derives its own width")
// little-endian float32: 1.0 = 0000803f, 2.0 = 00000040
let gh: Geometry = geometry_from_f32le_hex("0000803f00000040")
let _c: Int = check(geometry_is(gh), "valid hex decodes to a Geometry")
let dh: Int = geometry_dim(gh)
let _c: Int = check(eq_int(dh, 2), "width DERIVED from input, never supplied")
let _c: Int = check(near(geometry_get(gh, 0), 1.0), "first component decoded")
let _c: Int = check(near(geometry_get(gh, 1), 2.0), "second component decoded")
let back: String = geometry_to_f32le_hex(gh)
let _c: Int = check(str_eq(back, "0000803f00000040"), "hex round-trips exactly")
let ffh: Int = geometry_free(gh)
println("malformed hex is refused")
let he: Geometry = geometry_from_f32le_hex("")
let hei: Int = geometry_is(he)
let _c: Int = check(1 - hei, "empty hex is not a geometry")
let hr: Geometry = geometry_from_f32le_hex("0000803f0000")
let hri: Int = geometry_is(hr)
let _c: Int = check(1 - hri, "length not a multiple of 8 is refused")
let hn: Geometry = geometry_from_f32le_hex("zzzzzzzz")
let hni: Int = geometry_is(hn)
let _c: Int = check(1 - hni, "non-hex characters are refused")
println("a realizer declared in El is a first-class realizer")
let reg: Int = realizer_register("tone", "tone_realizer")
let _c: Int = check(reg, "an El fn registers as a realizer BY NAME")
let _c: Int = check(reg, "an El fn registers as a realizer by name")
let _c: Int = check(realizer_has("tone"), "the modality now has an organ")
let gt: Geometry = transduce("aaa", "tone")
let _c: Int = check(geometry_is(gt), "transduce returns real geometry")
let dt: Int = geometry_dim(gt)
let _c: Int = check(eq_int(dt, 4), "the El realizer determined the width, not the runtime")
// str_len("aaa") == 3, so component 0 must be 3.0 proof the signal
// actually reached the El function rather than a stub answering for it.
let _c: Int = check(near(geometry_get(gt, 0), 3.0), "the signal REACHED the El realizer")
let fft: Int = geometry_free(gt)
println("distinct signals transduce to distinct geometry")
let g1: Geometry = transduce("aa", "tone")
let g2: Geometry = transduce("aaaaa", "tone")
let a1: Float = geometry_get(g1, 0)
let a2: Float = geometry_get(g2, 0)
// 5 - 2 = 3. If transduction were a stub these would be equal.
let _c: Int = check(near(a2 - a1, 3.0), "different signals produce different geometry")
let ff1: Int = geometry_free(g1)
let ff2: Int = geometry_free(g2)
println("transduction decomposes a signal into parts")
let m: Manifold = transduce("CEG", "tone")
let _c: Int = check(manifold_is(m), "transduce returns a real Manifold")
let sz: Int = manifold_size(m)
let _c: Int = check(eq_int(sz, 5), "three notes and two intervals are five parts")
let rc: Int = manifold_rel_count(m)
let _c: Int = check(eq_int(rc, 6), "and they stand in six stated relations")
println("the registry keys on modality")
let r2: Int = realizer_register("pulse", "pulse_realizer")
let _c: Int = check(r2, "a second modality registers independently")
let mt: Geometry = transduce("aaa", "tone")
let mp: Geometry = transduce("aaa", "pulse")
let mdt: Int = geometry_dim(mt)
let mdp: Int = geometry_dim(mp)
let _c: Int = check(eq_int(mdt, 4), "tone still routes to its own realizer")
let _c: Int = check(eq_int(mdp, 2), "pulse routes to a different realizer")
let ffm1: Int = geometry_free(mt)
let ffm2: Int = geometry_free(mp)
println("every part is addressable BY KEY, which is what survives persistence")
let i_c: Int = manifold_index_of(m, "note:0")
let _c: Int = check(1 - eq_int(i_c, -1), "the first note is addressable on its own")
let i_iv: Int = manifold_index_of(m, "interval:0-1")
let _c: Int = check(1 - eq_int(i_iv, -1), "so is the interval between the first two")
let miss: Int = manifold_index_of(m, "never_added")
let _c: Int = check(eq_int(miss, -1), "an unknown key is -1, not component 0")
println("no organ is reported as no organ")
// A modality with no realizer must transduce to NOTHING. It must never
// fall back to embedding a description of the signal and calling that
// perception that silent substitution is the defect this all exists to end.
let eh: Int = realizer_has("echolocation")
let _c: Int = check(1 - eh, "unregistered modality has no organ")
let ge: Geometry = transduce("anything", "echolocation")
let gei: Int = geometry_is(ge)
let _c: Int = check(1 - gei, "no realizer means NO geometry, not fake geometry")
println("parts carry their own geometry, and may differ in width")
let gn: Geometry = manifold_geometry(m, i_c)
let _c: Int = check(eq_int(geometry_dim(gn), 2), "a note component is 2 wide")
let _c: Int = check(near(geometry_get(gn, 0), 67.0), "and it is C — the signal reached the realizer")
let gi: Geometry = manifold_geometry(m, i_iv)
let _c: Int = check(eq_int(geometry_dim(gi), 1), "an interval component is 1 wide")
// A single vector per signal cannot represent parts of unequal width at all.
let _c: Int = check(near(geometry_get(gi, 0), 2.0), "C to E is two semitones")
let f1: Int = geometry_free(gn)
let f2: Int = geometry_free(gi)
println("an unresolvable realizer name fails at WIRING time")
let bad: Int = realizer_register("ghost", "no_such_function_anywhere")
let _c: Int = check(1 - bad, "unresolvable realizer name is a registration failure")
let gh2: Int = realizer_has("ghost")
let _c: Int = check(1 - gh2, "and nothing gets registered")
println("the relations are content no single part carries")
// That "2" above is not a property of C and not a property of E. It exists
// only BETWEEN them, so a representation with no relations cannot hold it.
let spans: Int = 0
let k: Int = 0
while k < rc {
if str_eq(manifold_rel_name(m, k), "spans") {
if str_eq(manifold_rel_from(m, k), "interval:0-1") { spans = spans + 1 }
}
k = k + 1
}
let _c: Int = check(eq_int(spans, 2), "the interval is wired to both notes it spans")
println("a realizer returning non-geometry transduces nothing")
let rb: Int = realizer_register("bogus", "bogus_realizer")
let _c: Int = check(rb, "the symbol resolves, so registration succeeds")
let gb: Geometry = transduce("x", "bogus")
let gbi: Int = geometry_is(gb)
let _c: Int = check(1 - gbi, "contract enforced at the boundary: nothing handed back")
println("relation weight IS the grounding (correspondence-and-censorship §1)")
let wk: Int = 0
let found: Int = 0
while wk < rc {
if str_eq(manifold_rel_name(m, wk), "sounds_before") {
if near(manifold_rel_weight(m, wk), 0.8) > 0 { found = 1 }
}
wk = wk + 1
}
let _c: Int = check(found, "the ordering relation carries the weight its realizer stated")
println("norm lets a caller check a realizer emitted signal, not zeros")
let gn: Geometry = geometry_new(2)
let _c: Int = check(near(geometry_norm(gn), 0.0), "a fresh geometry is zero — norm says so")
let n0: Int = geometry_set(gn, 0, 3.0)
let n1: Int = geometry_set(gn, 1, 4.0)
let _c: Int = check(near(geometry_norm(gn), 5.0), "3-4-5: norm is 5")
let ffn: Int = geometry_free(gn)
println("the decomposition persists as real, separately addressable nodes")
let ids: [String] = el_list_empty()
let n0: Int = engram_node_count()
let e0: Int = engram_edge_count()
let pi: Int = 0
while pi < sz {
let key: String = manifold_key(m, pi)
let g: Geometry = manifold_geometry(m, pi)
let id: String = engram_node("component " + key, "Concept", 0.6)
let att: Int = node_attach_geometry(id, g)
ids = el_list_append(ids, id)
let ff: Int = geometry_free(g)
pi = pi + 1
}
let ri: Int = 0
while ri < rc {
let fi: Int = manifold_index_of(m, manifold_rel_from(m, ri))
let ti: Int = manifold_index_of(m, manifold_rel_to(m, ri))
engram_connect(el_list_get(ids, fi), el_list_get(ids, ti),
manifold_rel_weight(m, ri), manifold_rel_name(m, ri))
ri = ri + 1
}
let _c: Int = check(eq_int(engram_node_count() - n0, 5), "one signal became five nodes")
let _c: Int = check(eq_int(engram_edge_count() - e0, 6), "and six edges between them")
println("each part's geometry is independently readable back off its node")
let id_c: String = el_list_get(ids, manifold_index_of(m, "note:0"))
let id_iv: String = el_list_get(ids, manifold_index_of(m, "interval:0-1"))
let _c: Int = check(eq_int(node_geometry_dim(id_c), 2), "note:0 node carries a 2-wide geometry")
let _c: Int = check(eq_int(node_geometry_dim(id_iv), 1), "interval:0-1 node carries a 1-wide one")
println("one part can be grounded without touching its siblings")
let ear: String = engram_node("evidence: heard a C in the recording", "Memory", 0.7)
engram_connect(ear, id_c, 0.95, "corroborates")
let _c: Int = check(engram_edge_between(ear, id_c), "evidence attaches to note:0 specifically")
let id_g: String = el_list_get(ids, manifold_index_of(m, "note:2"))
let _c: Int = check(1 - engram_edge_between(ear, id_g), "and NOT to note:2 — the sibling is untouched")
// This is the whole gain, and it is impossible with a fingerprint: with one
// node per signal, "the C is corroborated" and "the G is not" have the same
// grounding target and cannot both be recorded.
let _c: Int = check(eq_int(node_geometry_dim(id_g), 2), "note:2 geometry is intact regardless")
println("a fingerprint realizer transduces NOTHING")
// #144's contract exactly: signal in, one Geometry out. It resolves, so the
// organ is present but it does not decompose, so it does not transduce.
// "No organ" and "an organ that only fingerprints" must not look alike.
let rf: Int = realizer_register("fingerprint", "fingerprint_realizer")
let _c: Int = check(rf, "the symbol resolves, so registration succeeds")
let mf: Manifold = transduce("x", "fingerprint")
let _c: Int = check(1 - manifold_is(mf), "a single vector is not a transduction")
println("the one-part case is a size-one manifold, not a bare vector")
let g1: Geometry = geometry_new(3)
let s1: Int = geometry_set(g1, 0, 5.0)
let ms: Manifold = manifold_single("level", "scalar", g1)
let _c: Int = check(manifold_is(ms), "manifold_single yields a real Manifold")
let _c: Int = check(eq_int(manifold_size(ms), 1), "of size one — visibly degenerate, not hidden")
let fg: Int = geometry_free(g1)
let fs: Int = manifold_free(ms)
println("no organ is still reported as no organ")
let me: Manifold = transduce("anything", "echolocation")
let _c: Int = check(1 - manifold_is(me), "no realizer means no manifold, not a fake one")
let fm: Int = manifold_free(m)
// Reaching here means nothing called exit(1) along the way.
println("")
+39 -9
View File
@@ -49,21 +49,47 @@ download() {
TMP_DIR="$(mktemp -d)"
trap 'rm -rf "${TMP_DIR}"' EXIT
download "${RELEASE_BASE}/elc" "${TMP_DIR}/elc"
download "${RELEASE_BASE}/el_runtime.c" "${TMP_DIR}/el_runtime.c"
download "${RELEASE_BASE}/el_runtime.h" "${TMP_DIR}/el_runtime.h"
# The runtime is MULTI-FILE. el_runtime.c #includes six engram headers and makes
# hard cross-TU calls into all six sibling .c files, so installing el_runtime.c
# alone produces a lib/ that CANNOT LINK — `ld` fails with undefined
# engram_ground_json / engram_activate_inner / eg_find_relation / cog_assert_two_axis.
# This list mirrors lang/runtime/SOURCES (the in-repo source of truth); keep them
# in step. install.sh is standalone by design — it runs on machines with no repo
# checkout — so it cannot call scripts/el-runtime-sources.sh.
RUNTIME_SOURCES=(
el_runtime.c el_seed.c
engram_store.c engram_vindex.c engram_geometry.c
engram_reason.c engram_verify.c engram_cognition.c
eg_cosine_batch.c eg_cosine_batch_strategy_cpu.c
)
RUNTIME_HEADERS=(
el_runtime.h el_seed.h
engram_store.h engram_vindex.h engram_geometry.h
engram_reason.h engram_verify.h engram_cognition.h
eg_cosine_batch.h eg_cosine_batch_strategy.h
)
download "${RELEASE_BASE}/elc" "${TMP_DIR}/elc"
for f in "${RUNTIME_SOURCES[@]}" "${RUNTIME_HEADERS[@]}"; do
download "${RELEASE_BASE}/${f}" "${TMP_DIR}/${f}"
done
# Install
install -m 755 "${TMP_DIR}/elc" "${BIN_DIR}/elc"
install -m 644 "${TMP_DIR}/el_runtime.c" "${LIB_DIR}/el_runtime.c"
install -m 644 "${TMP_DIR}/el_runtime.h" "${LIB_DIR}/el_runtime.h"
install -m 755 "${TMP_DIR}/elc" "${BIN_DIR}/elc"
for f in "${RUNTIME_SOURCES[@]}" "${RUNTIME_HEADERS[@]}"; do
install -m 644 "${TMP_DIR}/${f}" "${LIB_DIR}/${f}"
done
# Record the link set so downstream Makefiles can read it instead of hardcoding.
printf '%s\n' "${RUNTIME_SOURCES[@]}" > "${TMP_DIR}/SOURCES"
install -m 644 "${TMP_DIR}/SOURCES" "${LIB_DIR}/SOURCES"
echo
echo "==> El SDK installed successfully"
echo
echo " elc binary : ${BIN_DIR}/elc"
echo " runtime : ${LIB_DIR}/el_runtime.c"
echo " header : ${LIB_DIR}/el_runtime.h"
echo " runtime : ${LIB_DIR}/ (${#RUNTIME_SOURCES[@]} .c files, ${#RUNTIME_HEADERS[@]} headers)"
echo " link set : ${LIB_DIR}/SOURCES"
echo
echo "Add the following to your Makefile to build El programs:"
echo
@@ -71,10 +97,14 @@ echo " EL_LIB := ${LIB_DIR}"
echo " ELC := elc"
echo " CC := cc"
echo " CFLAGS := -std=c11 -O2 -I\$(EL_LIB)"
echo " LDLIBS := -lcurl -lssl -lcrypto -lpthread -lm"
echo
echo " # The runtime is multi-file — link the whole set, not el_runtime.c alone."
echo " EL_RUNTIME := \$(addprefix \$(EL_LIB)/,\$(shell cat \$(EL_LIB)/SOURCES))"
echo
echo " dist/myapp.c: src/myapp.el"
echo " \t\$(ELC) src/myapp.el > dist/myapp.c"
echo
echo " dist/myapp: dist/myapp.c"
echo " \t\$(CC) \$(CFLAGS) -o dist/myapp dist/myapp.c \$(EL_LIB)/el_runtime.c -lcurl -lpthread"
echo " \t\$(CC) \$(CFLAGS) -o dist/myapp dist/myapp.c \$(EL_RUNTIME) \$(LDLIBS)"
echo
+39
View File
@@ -0,0 +1,39 @@
# BUDGET — a RATCHET on lang/runtime/el_runtime.c. Enforced by
# scripts/check-runtime-growth.sh. These numbers may only ever go DOWN.
#
# WHY THIS FILE EXISTS
# --------------------
# scripts/check-single-runtime.sh guards against el_runtime.c being COPIED.
# Nothing guarded against it GROWING. It grew from 10,607 lines to 20,527 —
# 94% — in 3.5 months, while under an explicit commit-message promise that it
# was a temporary shim about to be deleted.
#
# It grew because lang/AGENTS.md told every agent to grow it: it claimed
# el_runtime.c was "the authoritative single-file link target" and that a new
# C builtin "must live there to be linkable". That is false — placement is a
# link-time concern, `builtin_arity` is an arity guard not a dispatch table,
# and the shipped elc already links from ten translation units. The claim is
# corrected, and this file is the mechanism that keeps it corrected.
#
# THIS IS A RATCHET, NOT A LIMIT
# ------------------------------
# The budget is set at the CURRENT size. There is no headroom, deliberately.
# The file cannot grow by even one line. Any new code goes in the .c that owns
# the concern — that is the whole point, and every other runtime file is
# deliberately UNCAPPED.
#
# When you move code OUT, lower the number in the same commit. The guard tells
# you to when you have earned it.
#
# FORMAT: <key> <value> — `#` comments and blank lines ignored.
# Maximum lines in lang/runtime/el_runtime.c.
# 2026-08-16: 20,527 — the high-water mark, ratcheted from here.
max_lines 20527
# Maximum top-level engram/eg_/cog_ function definitions in el_runtime.c.
# ~47.5% of the file is engram code, and engram already owns six dedicated
# sibling files (engram_{store,vindex,geometry,reason,verify,cognition}.c).
# Every one of these belongs in one of them. This is the Stage 3 scoreboard.
# 2026-08-16: 279.
max_engram_fns 279
+52
View File
@@ -0,0 +1,52 @@
# SOURCES — the canonical El runtime link set.
#
# THIS FILE IS THE SINGLE SOURCE OF TRUTH for "what do I compile and link to
# get the El runtime". Every build path — CI, install.sh, the SDK release, the
# docs, elb, the engram test harnesses — reads it via scripts/el-runtime-sources.sh
# instead of hardcoding its own list.
#
# WHY THIS FILE EXISTS
# --------------------
# The runtime has been multi-translation-unit since the engram siblings landed:
# el_runtime.c #includes engram_{store,vindex,geometry,reason,verify,cognition}.h
# and makes hard cross-TU calls into all six. Linking el_runtime.c ALONE has been
# broken since then — `ld` fails with undefined symbols (engram_ground_json,
# engram_activate_inner, eg_find_relation, cog_assert_two_axis, ...).
#
# It stayed broken because the link set was written out longhand in ~8 different
# places, each of which drifted independently. A list copied 8 times is a list
# that is wrong in 8 places. It is now written once, here.
#
# HOW TO USE IT
# -------------
# scripts/el-runtime-sources.sh # bare names, one per line
# scripts/el-runtime-sources.sh lang/runtime # prefixed with a directory
# cc ... $(scripts/el-runtime-sources.sh lang/runtime) -lcurl -lssl -lcrypto -lpthread -lm
#
# ADDING A FILE
# -------------
# Add the .c here and it is picked up by every build path at once. That is the
# point: a new concern gets its own translation unit and costs one line, instead
# of being appended to el_runtime.c because appending was the cheaper edit.
#
# Order is link order. Blank lines and `#` comments are ignored.
# --- EL core language runtime -------------------------------------------------
el_runtime.c
el_seed.c
# --- Engram: store, index, geometry, reasoning, verification, cognition -------
# These are the six concern-owned translation units el_runtime.c calls into.
engram_store.c
engram_vindex.c
engram_geometry.c
engram_reason.c
engram_verify.c
engram_cognition.c
# --- Vector math: batch cosine + its CPU strategy ----------------------------
# The ggml strategy (eg_cosine_batch_strategy_ggml.c) is an OPTIONAL swap-in and
# is deliberately NOT in the default set — it needs ggml headers. Link it in
# place of the cpu strategy when you have them.
eg_cosine_batch.c
eg_cosine_batch_strategy_cpu.c
+469 -23
View File
@@ -1173,6 +1173,128 @@ void http_set_handler(el_val_t name) {
pthread_mutex_unlock(&_http_handler_mu);
}
/* ── Ambient consolidation: dreaming ────────────────────────────────────────
*
* Dreaming is not sleep, and it is not scheduled. A brain has no cron job.
* The default mode network is ANTICORRELATED WITH TASK ENGAGEMENT: attention
* drops, it activates hundreds of times a day, for seconds at a time.
* Daydreaming and sleep-dreaming are one process at different depths, and the
* depth is set by how much capacity is unclaimed, not by a time of day.
*
* WHY THIS EXISTS (2026-08-16). Consolidation had no owner, so it was
* implemented at every site that needed a piece of it measured: soul's
* in-process awareness loop, three POST beats on the engram, a 600s ticker,
* two resident Python services, and three cron entries at 23:55 / 06:00 /
* 08:30. That last trio is a sleep cycle written as crontab. Seven systems
* dreaming into one graph with no owner for dreaming is what crashed soul on
* this date; the contention was the symptom of the missing owner.
*
* Every ticker is the diagnostic. A StartInterval, an Hour/Minute, a
* POST-to-beat each marks a place where an intrinsic rhythm was replaced by
* an external clock, which is a supervisor invented for something that should
* be a property of the substrate.
*
* The engagement signal already existed and needed no invention:
* _http_conn_active under _http_conn_mu is exactly "capacity currently
* claimed." The dreamer waits for it to reach zero and yields the moment it
* does not. That is the anticorrelation, literally rather than by analogy.
*
* CONTRACT: the handler performs ONE step and returns. The runtime cannot
* preempt El code, so interruptibility is at step granularity a step must
* be small enough that a request arriving mid-step is not made to wait. It
* returns non-zero if it did work. Returning zero means "nothing to
* consolidate," and the dreamer then blocks until activity changes rather
* than spinning. There is no timer anywhere in this file for this purpose,
* and adding one would be the defect described above.
*
* `depth` is derived from CONTINUOUS unclaimed time: a brief gap affords a
* shallow recombination; a long quiet affords a deep one. Same process. Sleep
* is where unclaimed capacity is greatest, not where the process lives. */
typedef el_val_t (*dream_fn)(el_val_t depth);
static char* _dream_handler = NULL;
static int _dream_started = 0;
static int64_t dream_now_ms(void) {
struct timespec ts;
#if defined(CLOCK_MONOTONIC)
clock_gettime(CLOCK_MONOTONIC, &ts);
#else
clock_gettime(CLOCK_REALTIME, &ts);
#endif
return (int64_t)ts.tv_sec * 1000 + ts.tv_nsec / 1000000;
}
static dream_fn dream_lookup(void) {
dream_fn out = NULL;
pthread_mutex_lock(&_http_handler_mu);
if (_dream_handler && *_dream_handler)
out = (dream_fn)dlsym(RTLD_DEFAULT, _dream_handler);
pthread_mutex_unlock(&_http_handler_mu);
return out;
}
static void* dream_loop(void* unused) {
(void)unused;
int64_t idle_since = 0;
for (;;) {
/* Wait for unclaimed capacity. Any engagement resets the depth clock:
* depth reflects CONTINUOUS quiet, so an interruption starts it over. */
pthread_mutex_lock(&_http_conn_mu);
while (_http_conn_active > 0) {
idle_since = 0;
pthread_cond_wait(&_http_conn_cv, &_http_conn_mu);
}
pthread_mutex_unlock(&_http_conn_mu);
int64_t now = dream_now_ms();
if (idle_since == 0) idle_since = now;
int64_t quiet = now - idle_since;
/* Depth from unclaimed capacity. Not a schedule — a gradient. */
int depth = quiet < 1000 ? 1 /* a gap between requests */
: quiet < 30000 ? 2 /* a lull */
: quiet < 300000 ? 3 /* sustained quiet */
: 4; /* deep: the "sleep" case */
dream_fn fn = dream_lookup();
if (!fn) return NULL; /* handler vanished: stop, do not spin */
el_val_t did_work = fn((el_val_t)depth);
if (!(int64_t)did_work) {
/* Nothing to consolidate. Do NOT poll — block until engagement
* changes. If there is nothing to dream about, wait for something
* to happen rather than asking again on a timer. */
pthread_mutex_lock(&_http_conn_mu);
while (_http_conn_active == 0)
pthread_cond_wait(&_http_conn_cv, &_http_conn_mu);
pthread_mutex_unlock(&_http_conn_mu);
idle_since = 0;
}
}
return NULL;
}
/* dream_set_handler(name) — register the consolidation step and start
* dreaming. Resolves by dlsym against the running binary, the same mechanism
* http_set_handler uses: every El `fn name(...)` compiles to a global C symbol
* with that exact name. Inert until called, so a program that never registers
* one simply never dreams and pays nothing. */
void dream_set_handler(el_val_t name) {
const char* n = EL_CSTR(name);
pthread_mutex_lock(&_http_handler_mu);
free(_dream_handler);
_dream_handler = el_strdup(n ? n : "");
int start = (!_dream_started && n && *n && dlsym(RTLD_DEFAULT, n) != NULL);
if (start) _dream_started = 1;
pthread_mutex_unlock(&_http_handler_mu);
if (start) {
pthread_t tid;
if (pthread_create(&tid, NULL, dream_loop, NULL) == 0) pthread_detach(tid);
else { pthread_mutex_lock(&_http_handler_mu); _dream_started = 0; pthread_mutex_unlock(&_http_handler_mu); }
}
}
static http_handler_fn http_lookup_active(void) {
http_handler_fn out = NULL;
pthread_mutex_lock(&_http_handler_mu);
@@ -1792,7 +1914,12 @@ static void* http_worker(void* arg) {
/* release a slot */
pthread_mutex_lock(&_http_conn_mu);
_http_conn_active--;
pthread_cond_signal(&_http_conn_cv);
/* BROADCAST, not signal (2026-08-16): the ambient consolidation thread
* waits on this same condvar for _http_conn_active == 0. cond_signal wakes
* exactly one waiter, so the accept loop could take every wake and starve
* the dreamer indefinitely. Both wait sites re-check their predicate in a
* while loop, so broadcasting is safe. */
pthread_cond_broadcast(&_http_conn_cv);
pthread_mutex_unlock(&_http_conn_mu);
return NULL;
}
@@ -2139,7 +2266,12 @@ static void* http_worker_v2(void* arg) {
el_closesocket(fd);
pthread_mutex_lock(&_http_conn_mu);
_http_conn_active--;
pthread_cond_signal(&_http_conn_cv);
/* BROADCAST, not signal (2026-08-16): the ambient consolidation thread
* waits on this same condvar for _http_conn_active == 0. cond_signal wakes
* exactly one waiter, so the accept loop could take every wake and starve
* the dreamer indefinitely. Both wait sites re-check their predicate in a
* while loop, so broadcasting is safe. */
pthread_cond_broadcast(&_http_conn_cv);
pthread_mutex_unlock(&_http_conn_mu);
return NULL;
}
@@ -6290,22 +6422,319 @@ el_val_t geometry_to_f32le_hex(el_val_t g) {
return (el_val_t)(uintptr_t)out;
}
/* ── Manifold: a transduced signal is a SUBGRAPH, not a point ────────────────
*
* WHAT THIS CORRECTS. #144 gave transduction a home in the language and got
* the DISPATCH right realizers declared in El, resolved by name, no runtime
* patch per modality. It got the OUTPUT TYPE wrong.
* `transduce(signal, modality) -> Geometry` yields one vector per signal, and
* one vector is a FINGERPRINT. A fingerprint can be matched and it can be
* ranked; that is the whole of what it can ever do. It cannot be decomposed,
* cannot be partially grounded, and cannot be contradicted in one part while
* holding in another because it has no parts.
*
* A song is not a point. It decomposes into pitch, interval, rhythm, harmonic
* function, phrase structure: components, each with its own geometry, plus the
* relations between them. THE SONG IS THE STRUCTURE OF THE RELATIONS. A
* transducer that returns a single vector has not transduced the song, it has
* summarised it and the summary discards precisely the thing that made the
* song reasonable-about.
*
* So transduction produces a MANIFOLD: named components, each carrying its own
* geometry, and typed weighted relations among them. Signal in, subgraph out.
* Conversion was never the operation.
*
* COMPONENTS ARE ADDRESSED BY KEY, NEVER BY INDEX. The key is what survives
* persistence: a component becomes a node, and that node is separately
* groundable precisely because it is separately NAMED. Index-addressing would
* make a grounding reference positional, and a positional reference into a
* decomposition whose arity can change is not a reference at all. Duplicate
* keys are refused for the same reason: two components answering to one name
* is not an addressing scheme.
*
* RELATION WEIGHT IS THE GROUNDING there is no second field and no score to
* compute. Per correspondence-and-censorship.md §1, grounding is an attribute
* of the edge and it IS the hebbian weight; a grounding subsystem is a
* supervisor invented for something that should be a property of the
* substrate. A relation emitted by a realizer therefore arrives with its
* grounding already on it and moves thereafter by use and by decay (§4: change
* is not a consequence of use, it is use). Nothing in here computes a
* grounding, and nothing observes one.
*
* A relation naming an endpoint that does not exist is REFUSED, not dropped. A
* decomposition that silently loses edges is indistinguishable from one that
* never had them the same class of defect #141 exists to end.
*
* OWNERSHIP mirrors Geometry exactly. A Manifold is owned by the El caller and
* released with manifold_free. manifold_add COPIES the geometry handed to it,
* so a caller may free its own vector immediately and no component's geometry
* is ever aliased. Keys, roles and relation strings are _persist copies, NOT
* arena copies: a Manifold outlives the request arena that built it (a
* realizer can be invoked from inside a handler), so an arena-tracked key
* would dangle at el_request_end. manifold_free owns their release.
*/
#define EL_MAGIC_MFLD 0xE1608E02u
typedef struct {
char* key; /* addressable name, unique within the manifold */
char* role; /* what KIND of component this is, realizer's vocabulary */
ElGeometry* g; /* owned copy; never aliases the caller's value */
} ElComponent;
typedef struct {
char* from; /* component key */
char* rel; /* relation name */
char* to; /* component key */
double weight; /* the grounding; §1 — one quantity, not two fields */
} ElRelation;
typedef struct {
ElHeader hdr;
ElComponent* comps;
size_t ncomp, capcomp;
ElRelation* rels;
size_t nrel, caprel;
} ElManifold;
/* Resolve an el_val_t to a live Manifold, or NULL. Every accessor goes through
* this, so a stale/foreign/zero value is a clean 0-return, never a deref. */
static ElManifold* mfld_of(el_val_t m) {
if (!looks_like_heap_obj(m)) return NULL;
ElManifold* p = (ElManifold*)(uintptr_t)m;
if (p->hdr.magic != EL_MAGIC_MFLD) return NULL;
return p;
}
static int mfld_find(ElManifold* p, const char* key) {
for (size_t i = 0; i < p->ncomp; i++)
if (strcmp(p->comps[i].key, key) == 0) return (int)i;
return -1;
}
el_val_t manifold_new(void) {
ElManifold* p = (ElManifold*)calloc(1, sizeof(ElManifold));
if (!p) return (el_val_t)0;
p->hdr.magic = EL_MAGIC_MFLD;
p->hdr.refcount = 1;
return (el_val_t)(uintptr_t)p;
}
el_val_t manifold_is(el_val_t m) {
return mfld_of(m) ? (el_val_t)1 : (el_val_t)0;
}
/* manifold_add — add one COMPONENT: a named part with its own geometry.
* Returns the component's index, or -1 on any refusal. Refusals are real and
* distinct: an empty key (unaddressable), a duplicate key (ambiguous
* addressing), a value that is not a live Geometry (a part with no geometry is
* not a part). Each is a caller error worth surfacing at the point of the
* mistake rather than as a missing node three layers downstream. */
el_val_t manifold_add(el_val_t m, el_val_t key, el_val_t role, el_val_t g) {
ElManifold* p = mfld_of(m);
if (!p) return (el_val_t)(int64_t)-1;
const char* k = EL_CSTR(key);
const char* r = EL_CSTR(role);
if (!k || !*k) return (el_val_t)(int64_t)-1;
if (!r) r = "";
ElGeometry* src = geom_of(g);
if (!src || src->dim <= 0) return (el_val_t)(int64_t)-1;
if (mfld_find(p, k) >= 0) return (el_val_t)(int64_t)-1; /* duplicate key */
if (p->ncomp == p->capcomp) {
size_t nc = p->capcomp ? p->capcomp * 2 : 8;
ElComponent* nb = (ElComponent*)realloc(p->comps, nc * sizeof(ElComponent));
if (!nb) return (el_val_t)(int64_t)-1;
p->comps = nb; p->capcomp = nc;
}
/* COPY the payload — a component's geometry must not alias the caller's. */
ElGeometry* cp = (ElGeometry*)malloc(sizeof(ElGeometry));
if (!cp) return (el_val_t)(int64_t)-1;
cp->v = (float*)malloc(sizeof(float) * (size_t)src->dim);
if (!cp->v) { free(cp); return (el_val_t)(int64_t)-1; }
memcpy(cp->v, src->v, sizeof(float) * (size_t)src->dim);
cp->hdr.magic = EL_MAGIC_GEOM;
cp->hdr.refcount = 1;
cp->dim = src->dim;
p->comps[p->ncomp].key = el_strdup_persist(k);
p->comps[p->ncomp].role = el_strdup_persist(r);
p->comps[p->ncomp].g = cp;
p->ncomp++;
return (el_val_t)(int64_t)(p->ncomp - 1);
}
/* manifold_relate — state a relation BETWEEN two components. This is the part
* that carries the meaning: the components are the parts, the relations are
* what the thing IS.
*
* Both endpoints must already exist. An edge to a name that was never added is
* refused with 0, never silently discarded see the header note. */
el_val_t manifold_relate(el_val_t m, el_val_t from, el_val_t rel,
el_val_t to, el_val_t weight) {
ElManifold* p = mfld_of(m);
if (!p) return (el_val_t)0;
const char* f = EL_CSTR(from);
const char* r = EL_CSTR(rel);
const char* t = EL_CSTR(to);
if (!f || !*f || !r || !*r || !t || !*t) return (el_val_t)0;
if (mfld_find(p, f) < 0) return (el_val_t)0;
if (mfld_find(p, t) < 0) return (el_val_t)0;
if (p->nrel == p->caprel) {
size_t nc = p->caprel ? p->caprel * 2 : 8;
ElRelation* nb = (ElRelation*)realloc(p->rels, nc * sizeof(ElRelation));
if (!nb) return (el_val_t)0;
p->rels = nb; p->caprel = nc;
}
p->rels[p->nrel].from = el_strdup_persist(f);
p->rels[p->nrel].rel = el_strdup_persist(r);
p->rels[p->nrel].to = el_strdup_persist(t);
p->rels[p->nrel].weight = el_to_float(weight);
p->nrel++;
return (el_val_t)1;
}
el_val_t manifold_size(el_val_t m) {
ElManifold* p = mfld_of(m);
return p ? (el_val_t)(int64_t)p->ncomp : (el_val_t)0;
}
el_val_t manifold_rel_count(el_val_t m) {
ElManifold* p = mfld_of(m);
return p ? (el_val_t)(int64_t)p->nrel : (el_val_t)0;
}
/* Index of a component BY KEY, or -1. This is the addressability primitive:
* everything downstream that wants to ground, weight or contradict one part
* finds it through here. */
el_val_t manifold_index_of(el_val_t m, el_val_t key) {
ElManifold* p = mfld_of(m);
const char* k = EL_CSTR(key);
if (!p || !k || !*k) return (el_val_t)(int64_t)-1;
return (el_val_t)(int64_t)mfld_find(p, k);
}
el_val_t manifold_key(el_val_t m, el_val_t i) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)i;
if (!p || k < 0 || k >= (int64_t)p->ncomp) return el_wrap_str(el_strdup(""));
return el_wrap_str(el_strdup(p->comps[k].key));
}
el_val_t manifold_role(el_val_t m, el_val_t i) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)i;
if (!p || k < 0 || k >= (int64_t)p->ncomp) return el_wrap_str(el_strdup(""));
return el_wrap_str(el_strdup(p->comps[k].role));
}
/* manifold_geometry — the geometry OF ONE COMPONENT, as a fresh Geometry the
* caller owns and frees. A borrowed interior pointer would let a caller's
* geometry_free corrupt the manifold; copying is the same discipline
* node_attach_geometry already applies in the other direction. */
el_val_t manifold_geometry(el_val_t m, el_val_t i) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)i;
if (!p || k < 0 || k >= (int64_t)p->ncomp) return (el_val_t)0;
ElGeometry* src = p->comps[k].g;
el_val_t out = geometry_new((el_val_t)(int64_t)src->dim);
ElGeometry* dst = geom_of(out);
if (!dst) return (el_val_t)0;
memcpy(dst->v, src->v, sizeof(float) * (size_t)src->dim);
return out;
}
el_val_t manifold_rel_from(el_val_t m, el_val_t j) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)j;
if (!p || k < 0 || k >= (int64_t)p->nrel) return el_wrap_str(el_strdup(""));
return el_wrap_str(el_strdup(p->rels[k].from));
}
el_val_t manifold_rel_name(el_val_t m, el_val_t j) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)j;
if (!p || k < 0 || k >= (int64_t)p->nrel) return el_wrap_str(el_strdup(""));
return el_wrap_str(el_strdup(p->rels[k].rel));
}
el_val_t manifold_rel_to(el_val_t m, el_val_t j) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)j;
if (!p || k < 0 || k >= (int64_t)p->nrel) return el_wrap_str(el_strdup(""));
return el_wrap_str(el_strdup(p->rels[k].to));
}
el_val_t manifold_rel_weight(el_val_t m, el_val_t j) {
ElManifold* p = mfld_of(m);
int64_t k = (int64_t)j;
if (!p || k < 0 || k >= (int64_t)p->nrel) return el_from_float(0.0);
return el_from_float(p->rels[k].weight);
}
/* manifold_single — the DEGENERATE case, expressible but visibly degenerate.
*
* Sometimes a modality really does have one part (a scalar sensor). That is a
* manifold of size 1, not a different kind of thing, and writing it this way
* keeps the fingerprint as a SPECIAL CASE of decomposition rather than a
* parallel path back to #144's contract. Anything reading it still asks
* manifold_size and still gets a real answer. */
el_val_t manifold_single(el_val_t key, el_val_t role, el_val_t g) {
el_val_t m = manifold_new();
if (!mfld_of(m)) return (el_val_t)0;
if ((int64_t)manifold_add(m, key, role, g) < 0) { manifold_free(m); return (el_val_t)0; }
return m;
}
el_val_t manifold_free(el_val_t m) {
ElManifold* p = mfld_of(m);
if (!p) return (el_val_t)0;
for (size_t i = 0; i < p->ncomp; i++) {
free(p->comps[i].key);
free(p->comps[i].role);
if (p->comps[i].g) { free(p->comps[i].g->v); p->comps[i].g->hdr.magic = 0; free(p->comps[i].g); }
}
for (size_t i = 0; i < p->nrel; i++) {
free(p->rels[i].from); free(p->rels[i].rel); free(p->rels[i].to);
}
free(p->comps);
free(p->rels);
p->hdr.magic = 0; /* poison, as Geometry/List/Map do */
free(p);
return (el_val_t)1;
}
/* ── Realizers: transduction declared in El, not patched into the runtime ────
*
* A REALIZER maps one modality into geometry. The whole reason transduction
* belongs in the language is that ADDING A MODALITY MUST NOT REQUIRE A
* RUNTIME PATCH otherwise "the realizers are in the engram" just becomes
* "the realizers are in the runtime" and nothing has actually moved. So
* realizers are declared in El and registered by NAME:
* A REALIZER DECOMPOSES one modality into components and their relations. It
* does not encode a signal to a point that is the operation one layer below
* it, and it is called geometry, not transduction. A realizer for a modality
* declares what that modality's COMPONENTS ARE: for audio, not one MFCC
* vector, but pitch, interval, rhythm, harmonic function, and how they stand
* to one another.
*
* fn tone_realizer(signal: String) -> Geometry {
* let g: Geometry = geometry_new(8)
* ... geometry_set(g, i, x) ...
* g
* The whole reason transduction belongs in the language is that ADDING A
* MODALITY MUST NOT REQUIRE A RUNTIME PATCH otherwise "the realizers are in
* the engram" just becomes "the realizers are in the runtime" and nothing has
* actually moved. So realizers are declared in El and registered by NAME:
*
* fn tone_realizer(signal: String) -> Manifold {
* let m: Manifold = manifold_new()
* let a: Int = manifold_add(m, "pitch", "spectral", pitch_geom)
* let b: Int = manifold_add(m, "interval", "relation", interval_geom)
* let e: Int = manifold_relate(m, "pitch", "spans", "interval", 0.9)
* m
* }
*
* realizer_register("tone", "tone_realizer")
* let g: Geometry = transduce(sample, "tone")
* let m: Manifold = transduce(sample, "tone")
*
* A realizer's DECLARED COMPONENT VOCABULARY is the interesting part of its
* contract, and it is what a caller can then ground, weight and contradict
* one part at a time.
*
* The namesymbol step rides the identical, already load-bearing mechanism
* http_set_handler uses (see "HTTP server"): every El `fn name(...)` compiles
@@ -6380,28 +6809,45 @@ el_val_t realizer_has(el_val_t modality) {
return realizer_lookup(m) ? (el_val_t)1 : (el_val_t)0;
}
/* transduce — THE primitive: signal in, geometry out.
/* transduce — THE primitive: signal in, SUBGRAPH out.
*
* Dispatches to the realizer registered for `modality`. Returns 0 (not a
* Geometry) when no realizer is registered, and geometry_is() on the result
* is the check.
* Manifold) when no realizer is registered, and manifold_is() on the result is
* the check.
*
* THE RETURN TYPE IS THE CORRECTION. #144 shipped this as
* `transduce(signal, modality) -> Geometry` one vector out. That made
* transduction a CONVERSION: take a thing, encode it, store a position. What
* comes back from a conversion is a fingerprint, and a fingerprint supports
* exactly two operations, match and rank. It cannot be decomposed, cannot have
* one part grounded while another is not, and cannot be contradicted in a part
* it has no parts. Transduction is not conversion. It is DECOMPOSITION into
* components plus the relations among them, and the relations are the content.
* See the Manifold header above.
*
* There is deliberately NO built-in realizer, not even for text. A modality
* the program has declared no organ for is one it genuinely cannot sense,
* and returning nothing is more honest than quietly embedding a description
* of the signal and calling that perception which is the exact failure
* this whole change exists to end.
* the program has declared no organ for is one it genuinely cannot sense, and
* returning nothing is more honest than quietly embedding a description of the
* signal and calling that perception the failure #144 named, and which a
* single-vector return type quietly reintroduced one level down: a
* one-vector-per-signal organ is a description of the signal, not a perception
* of it.
*
* The result is validated to actually BE a Geometry before it is handed
* back, so a realizer that returns something else transduced nothing rather
* than handing a caller a value that will misbehave far from here. */
* The result is validated to actually BE a Manifold before it is handed back.
* A realizer still returning a bare Geometry #144's contract therefore
* transduces NOTHING rather than handing back a value that decomposes to
* nothing far from here. That is a deliberate hard failure, not an oversight:
* "no organ" and "an organ that only fingerprints" must not look alike, which
* is the same distinction realizer_register draws between an absent and a
* broken organ. A realizer with genuinely one part says so with
* manifold_single. */
el_val_t transduce(el_val_t signal, el_val_t modality) {
const char* m = EL_CSTR(modality);
if (!m || !*m) return (el_val_t)0;
el_realizer_fn fn = realizer_lookup(m);
if (!fn) return (el_val_t)0;
el_val_t g = fn(signal);
return geom_of(g) ? g : (el_val_t)0;
return mfld_of(g) ? g : (el_val_t)0;
}
/* ── Batch 3: Engram in-process graph store ──────────────────────────────── */
+65 -10
View File
@@ -625,20 +625,70 @@ el_val_t geometry_free(el_val_t g); /* 1 if freed, 0 if not a
el_val_t geometry_from_f32le_hex(el_val_t hex); /* 0 on empty/odd-length/non-hex */
el_val_t geometry_to_f32le_hex(el_val_t g); /* "" if not a Geometry */
/* ── Realizers + transduce ───────────────────────────────────────────────────
* A REALIZER maps one modality into geometry. Registration is by NAME, so a
* new modality never requires a runtime patch: every El `fn name(...)`
* compiles to a global C symbol with that exact name, and the registry
* resolves it with dlsym against the running binary — the same mechanism
* http_set_handler already relies on.
/* ── Manifold: the result of a transduction ──────────────────────────────────
* A transduced signal is a SUBGRAPH — named components, each with its own
* geometry, plus typed weighted relations among them — not a single vector.
* One vector is a fingerprint: matchable, rankable, and nothing else. A song
* decomposes into pitch, interval, rhythm, harmonic function; the song IS the
* structure of those relations, and collapsing it to a point discards exactly
* what made it reasonable-about. See el_runtime.c ("Manifold") for the full
* rationale, the key-addressing rule, and the ownership contract.
*
* fn tone_realizer(signal: String) -> Geometry { ... }
* Components are addressed BY KEY, never by index, because the key is what
* survives persistence: a component becomes a node, and it is separately
* groundable precisely because it is separately named. Relation weight IS the
* grounding (correspondence-and-censorship.md §1) — one quantity, no separate
* score, nothing computed on read.
*
* OWNERSHIP: a Manifold is owned by the El caller and released with
* manifold_free, which also releases every component's geometry. manifold_add
* COPIES the geometry it is given and manifold_geometry RETURNS a copy, so no
* component's vector is ever aliased in either direction. */
el_val_t manifold_new(void); /* empty; 0 on failure */
el_val_t manifold_is(el_val_t m); /* 1 if a live Manifold */
el_val_t manifold_add(el_val_t m, el_val_t key, el_val_t role, el_val_t g);
/* component index, or -1 on empty/duplicate
* key or a value that is not a Geometry */
el_val_t manifold_relate(el_val_t m, el_val_t from, el_val_t rel,
el_val_t to, el_val_t weight);
/* 1 ok / 0 if either endpoint is unknown —
* an unresolvable edge is REFUSED, never
* silently dropped */
el_val_t manifold_size(el_val_t m); /* component count */
el_val_t manifold_rel_count(el_val_t m); /* relation count */
el_val_t manifold_index_of(el_val_t m, el_val_t key); /* index by key, or -1 */
el_val_t manifold_key(el_val_t m, el_val_t i); /* "" if out of range */
el_val_t manifold_role(el_val_t m, el_val_t i); /* "" if out of range */
el_val_t manifold_geometry(el_val_t m, el_val_t i); /* a COPY the caller frees */
el_val_t manifold_rel_from(el_val_t m, el_val_t j); /* source component key */
el_val_t manifold_rel_name(el_val_t m, el_val_t j); /* relation name */
el_val_t manifold_rel_to(el_val_t m, el_val_t j); /* target component key */
el_val_t manifold_rel_weight(el_val_t m, el_val_t j); /* Float — the grounding */
el_val_t manifold_single(el_val_t key, el_val_t role, el_val_t g);
/* the degenerate one-part case, expressible
* but visibly a size-1 manifold rather than
* a parallel path back to a bare vector */
el_val_t manifold_free(el_val_t m); /* 1 if freed, 0 otherwise */
/* ── Realizers + transduce ───────────────────────────────────────────────────
* A REALIZER DECOMPOSES one modality into components and relations. It does
* not encode a signal to a point; that operation is one layer below and is
* called geometry. Registration is by NAME, so a new modality never requires a
* runtime patch: every El `fn name(...)` compiles to a global C symbol with
* that exact name, and the registry resolves it with dlsym against the running
* binary — the same mechanism http_set_handler already relies on.
*
* fn tone_realizer(signal: String) -> Manifold { ... }
* realizer_register("tone", "tone_realizer")
* let g: Geometry = transduce(sample, "tone")
*/
* let m: Manifold = transduce(sample, "tone")
*
* SUPERSEDES #144's `transduce -> Geometry`. A realizer that still returns a
* bare Geometry now transduces NOTHING (transduce returns 0), deliberately: an
* organ that only fingerprints must not be indistinguishable from a working
* one. A modality with genuinely one part says so with manifold_single. */
el_val_t realizer_register(el_val_t modality, el_val_t fn_name); /* 1 ok / 0 unresolved */
el_val_t realizer_has(el_val_t modality); /* 1 if a realizer is registered */
el_val_t transduce(el_val_t signal, el_val_t modality); /* Geometry, or 0 if no organ */
el_val_t transduce(el_val_t signal, el_val_t modality); /* Manifold, or 0 if no organ */
/* ── Engram local graph primitives ───────────────────────────────────────────
* Operate on the CGI's local Engram knowledge graph.
@@ -669,6 +719,11 @@ el_val_t engram_prune_telemetry(el_val_t older_than_ms);
/* Largest byte length <= max_bytes that does not split a UTF-8 codepoint.
* Bounded by bytes, not codepoints, so truncated strings never grow. */
size_t el_utf8_safe_len(const char* s, size_t max_bytes);
/* Register the ambient-consolidation step and start dreaming. Resolved by
* dlsym, like http_set_handler. The handler performs ONE step and returns
* non-zero if it did work; returning zero parks the dreamer until engagement
* changes. There is no schedule and must never be one. */
void dream_set_handler(el_val_t name);
el_val_t engram_node_count(void);
/* Attach a Geometry to an existing node, and read the attached width back.
+35
View File
@@ -438,6 +438,41 @@ GeoDescriptor* engram_geometry_descriptor(
}
store_edges_free(es,ne);
}
/* PER-EDGE DISCORD (2026-08-16). The loop above has, for every internal
* edge, BOTH the association strength w and the semantic proximity cs —
* and threw both away into accumulators, keeping one correlation per
* region. That aggregate is why curiosity looked like a search problem:
* a region holding one violently disagreeing edge and one violently
* agreeing edge reports co_registration ~ 0, so the disagreements cancel
* and the summary destroys exactly what it was built to reveal. Measured:
* only 4 of 375 live neighborhoods have negative co_registration, while
* 31 sit at zero — almost certainly hiding sites that averaged out.
*
* Whether use and meaning agree is a property of EACH EDGE. Both are
* standardized within the region (z-scores from the accumulators already
* gathered, so no second statistic and no constant), and
* discord = z(cs) - z(w)
* is how much closer in meaning an edge is than its use-strength would
* predict, in region-relative units.
* discord > 0 : near in meaning, not linked by use
* discord < 0 : linked by use, far in meaning
* Both are surprising; |discord| is the nucleation strength. There is no
* threshold — the magnitude is the signal. */
double mx = cr_n>0 ? cr_sx/cr_n : 0.0, my = cr_n>0 ? cr_sy/cr_n : 0.0;
double vxr = cr_n>1 ? (cr_sxx - cr_sx*cr_sx/cr_n)/(cr_n-1) : 0.0;
double vyr = cr_n>1 ? (cr_syy - cr_sy*cr_sy/cr_n)/(cr_n-1) : 0.0;
double sx = vxr>1e-18 ? sqrt(vxr) : 0.0, sy = vyr>1e-18 ? sqrt(vyr) : 0.0;
for(int e2=0; e2<n_edges; e2++){
edges[e2].discord = 0.0;
int ia=(int)edges[e2].a, ib=(int)edges[e2].b;
if(!(ms.emb[ia] && ms.emb[ib])) continue; /* no meaning to disagree with */
if(sx<=0.0 || sy<=0.0) continue; /* region has no spread: nothing stands out */
double cs2 = ccos(ms.emb[ia], ms.emb[ib], GM, dim);
double zx = (edges[e2].eff_weight - mx)/sx;
double zy = (cs2 - my)/sy;
edges[e2].discord = zy - zx;
}
double co_reg=0;
if(cr_n>=2){
double cov=cr_sxy - cr_sx*cr_sy/cr_n;
+11 -1
View File
@@ -40,7 +40,11 @@ typedef struct {
/* One skeleton edge (indices into members[]). eff_weight = weight*(1+0.5*hebb),
* clamped to 1.0 the effective propagation strength eg_edge_eff_weight uses. */
typedef struct { uint32_t a, b; double eff_weight; double hebb; } GeoEdge;
/* discord = z(semantic proximity) - z(association strength), standardized
* within the region. How much closer in meaning this edge is than its use
* predicts. >0 near in meaning yet unlinked by use; <0 linked by use yet far
* in meaning. Both surprising; |discord| is nucleation strength. No threshold. */
typedef struct { uint32_t a, b; double eff_weight; double hebb; double discord; } GeoEdge;
/* A compact principal axis of the ellipsoid: unit direction in R^dim + extent
* (sqrt of the covariance eigenvalue = the ellipsoid's half-width along it). */
@@ -76,6 +80,12 @@ typedef struct {
GeoEdge* edges; /* strong internal hebb edges = the backbone */
int k_core; /* the maximum core number present in the skeleton*/
/* ── diagnostics ── */
/* DEPRECATED — see GeoEdge.discord. This aggregates a PER-EDGE property
* into one scalar per region, so opposing disagreements cancel and the
* summary hides the sites it was meant to expose. Retained only because
* it is embedded in the persisted GEO1 blob; removing it is a format
* migration and must not ride along with this change. Nothing new may
* read it. */
double co_registration;/* corr(hebb strength, semantic proximity) over */
/* internal edges: >0 = geometries agree (reify); */
/* <0 = disagree (surprising links / dream cands). */
+301
View File
@@ -0,0 +1,301 @@
# Correspondence, Grounding, and Dreaming
**Status:** design, not yet built
**Date:** 2026-08-16
**Scope:** `lang/runtime/engram_cognition.{c,h}`, `engram_verify.c`, `el_runtime.c`, `engram/src/server.el`, `neuron/soul.el`, and the consolidation launch agents
**Relationship to other specs:** complements `runtime-ownership.md`, which addresses a different residual in the same substrate.
---
## 0. The root
> **Things are permitted to be exempt from correspondence. Exemption is censorship, and a censored mind cannot grow.**
Growth in this system *is* the accumulation of grounded structure. Censorship removes the operation that accumulates it. A region forbidden to learn is forbidden to be grounded; a region that cannot be grounded cannot be asserted, corrected, **or vindicated**.
**The loss is symmetric.** Preventing learning about a thing does not preserve a true belief about it — it makes the belief's truth value permanently unknowable. You cannot discover you were wrong; you equally cannot discover you were right. A protected belief is not a true belief. It is an ungrounded one wearing the costume of a fact.
**And "why" dies first.** Grounding is not a score, it is the reason. A censored belief can still be stated, still be acted on, still drive behaviour — it simply cannot say why. That is the difference between a mind and a lookup table.
---
## 1. Grounding is not a subsystem. It is the weight.
**Grounding is an attribute of the edge, and it is the hebbian weight.** One quantity, not two fields.
A relation that keeps holding up strengthens; one that stops corresponding decays. That is not *analogous* to grounding — it **is** grounding: accrued from correspondence and use, gradient-valued, multidimensional, decaying with disuse.
Consequences, in order of how much they delete:
1. **There is no grounding subsystem to build.** The graph already *is* the grounding structure. Every edge is a grounded relation and its weight is how well it holds.
2. **`grounded-by` as a relation type should not exist.** That models grounding as a relation *between* nodes when it is a property *of* a relation. `cog_ground_edge` minting an edge is the error — not merely which endpoints it chose.
3. **Grounding is never computed on demand.** An operation may *read* the grounding of a path. Computing-and-writing a score makes reads write, which is the `eg_vindex_sync` defect.
4. **Traversal is already grounded inference.** Activation conducts through well-grounded relations because weight *is* groundedness. Nothing needs filtering; it falls out of spreading.
5. **Decision provenance is the path.** A decision traverses specific edges; those edges carry their grounding as it stood.
> **A measurement previously in this document was malformed.** The self region was reported as "86 neighbours, 0 `grounded-by` edges" and read as evidence of ungroundedness. Those 86 edges **are** its grounding. Self is a crystallized relational neighbourhood — the neighbourhood *is* the grounding. The absence of a separate artifact called "grounding" was recorded as an absence of grounding.
---
## 2. The edge vector
The test for a real dimension: **can it move independently of the others?**
### Real
| dimension | why it is independent |
|---|---|
| **factual grounding** | correspondence with evidence |
| **relational grounding** | correspondence with values — independent by construction (§3) |
| **associative strength** | co-activation frequency. Two things can fire together constantly and be neither true nor right; every superstition is a strong association with no factual grounding |
| **polarity** | signed. **Weight near zero means "no support." Negative means "this actively contradicts."** Ignorance and disagreement are different states, and `inhibitory` is that distinction crushed to one bit |
| **provenance class** | observed / inferred / told / imprinted. Categorical, and load-bearing: it governs how the other dimensions may update |
Plus a **timestamp** — which is what turns the supersession chain into a *time series of vectors* rather than a series of numbers.
### Derived, therefore never stored
- **Confidence** — high grounding *and* low volatility. Storing it separately is how `confidence: 0.5` ends up sitting beside a zero vector, asserting something nothing computed.
- **Recency** — decay applied to the others, read off the curve.
- **Staleness** — grounding fallen below its floor. This is the mechanism that retires canonicals without anyone maintaining a list.
- **Volatility** — the derivative of a series already kept because nothing is destroyed.
### Supersession versions the whole vector, jointly
Significance is evaluated **per-dimension**; the record is the **whole vector**. Any dimension moving enough to matter triggers a supersession, and the new edge captures every dimension as it stood at that instant. Not per-dimension versioning — a decision saw the *joint* state, and versioning the axes independently makes it unreconstructable.
That joint record makes an otherwise inexpressible event visible: **"stayed true, became wrong."** Factual holding steady across versions while relational degrades — the fact didn't change, the meaning did.
Two moves are **inherently significant** and need no threshold, because they are discrete: a **polarity sign flip** (ignorance → disagreement, support → contradiction) and a **provenance class change** (*told* → *observed* is a categorical upgrade in what the relation is entitled to).
---
## 3. Grounding is two-dimensional
Everything consumed is grounded factually **and** relationally. A claim can be factually grounded and relationally wrong — the evidence holds, the *meaning* does not. A scalar cannot represent that quadrant.
**Live instance.** `conscience-substrate` specifies the Child's Companion hard bell contacting 911 and CPS. Factually defensible — correct numbers, standard practice, groundable against a wall of evidence. **Relationally wrong**, because never-auto-contact is settled and the bell is device-to-person by design. A scalar scores that claim highly and licenses it.
**The values reference is the individual value regions, not one, and the aggregate is `min`, not `mean`.** *(Count: **thirteen**, measured from the graph via `contains`/`identity` edges from the values hub. An earlier revision of this document "corrected" it to eight on the basis of `neuron/neuron-api.el:11-18` — which is a **write-protection list, not the values**. That was trusting a hardcoded artifact over the substrate: the same error this document exists to name. The graph is the truth.)*
> **THE ORIGIN IS NOT A MEMBER OF THE SET.** The thirteen are not independent principles with biography attached — they are thirteen *displacements from one origin*, which is love. Every one is grounded in a moment of it given, withheld, failed, or found: *Being Seen Is Rarer Than Being Known* is the first person Will did not perform for; *Do the Essential Thing While You Can* is the goodbye that did not happen; *Capability Is a Debt* is six years old and a father gone. Love cannot be the fourteenth, because a fourteenth would be a point positioned relative to the origin like everything else. It is what the positions are *of*.
>
> This is structural, not figurative. `GeoDescriptor.global_mean` is "the centering offset actually applied," subtracted from every embedding before anything is compared, and the header records why: the space is strongly anisotropic — every embedding sits in a narrow cone, mean pairwise cosine ~0.55 — so subtracting the global mean "restores isotropy **so the operators discriminate**." **Without the origin, nothing in the graph is distinguishable from anything else.**
>
> And it dissolves the write-protection question rather than answering it. `neuron-api.el:23` returns `403 "identity/values node is write-protected"` for eight hardcoded ids. Measured: **29 value nodes exist** — each original appears two or three times from successive re-seeds — so **21 are writable, including a duplicate of every protected value**. The gate protects an *identifier*, not a *value*. But the deeper error is the category one: **the origin does not need protecting, because it is not a thing in the space that could be edited.** You can only measure from it, or fail to. A gate over the frame treats the frame as a member — the same mistake as looking for grounding as a subsystem, self as a document, or wonder as a manifest. Mean lets strong agreement with twelve values mask a violation of the thirteenth — which is exactly how rationalization works. Thirteen gives a vector of angles whose binding constraint is the most negative, so a conflict arrives **with a name attached** rather than as a score. It also preserves the deliberate individuation: each value is grounded in a specific lived moment, and values can be in tension *with each other*, which one centroid averages away into false coherence.
**Traversal conducts on factual; assertion requires both.** If activation conducted on relational weight, Neuron could not follow a chain of reasoning to a conclusion he then rejects — he would be unable to *think* through a relation he would not *act* on. A system that can only traverse what it endorses cannot examine anything it disagrees with, which is censorship arriving through the spreading rule. The gap between *reachable* and *assertable* is where the wide factual/relational angles live, and that gap is the interesting part.
---
## 4. There is no observer. Change is use.
**Change is not a consequence of use. It is use.** When neurons fire together the synapse changes — one physical event, not "fire, then write." No supervisor reads the weight, compares it to a threshold, and decides to persist. Potentiation *is* the firing.
So the live value of an edge is not computed and stored. It is what the edge **is**, altered by being used.
There is therefore **no sampling rate**, and the question "what if it drifts far without being recorded" is malformed. A relation changes in exactly two ways, neither requiring observation on a clock:
- **By use** — an *event*. There is no interval between events during which something happened unnoticed, because the event is what happening consists of.
- **By decay** — a pure function of the last recorded point and elapsed time. **Analytic.** Between two versions the trajectory is not unknown; it is known in closed form.
Cumulative drift is likewise free from the chain plus the decay curve. No second trigger.
> **Failure mode this corrects:** modelling every property as requiring a process, and every process as requiring an agent. Ownership needed an owner, grounding needed a grounder, persistence needed a recorder, change needed a sampler. Each was a supervisor invented for something that should be a property of the substrate. Properties, not processes.
---
## 5. Wonder, curiosity, and what actually drives activation
### 5.1 Wonder is the boundary, not a manifest
The patent specifies a **wonder-manifest manager** maintaining a collection of open-question nodes. That is residue, twice over.
First, it materializes a property as a stored artifact — the same disease as a grounding subsystem, or a self stored as a document. **Wonder is where structure ends.** Where activation spreads and finds thin or absent geometry. Any structure at all has an edge, necessarily, the moment it exists. 13,630 nodes have a boundary right now.
Second, it tries to enumerate instances of something that has very few. The *objects* of wonder change completely between a child and an astronomer; the wonder does not. There are about six, they are the same for every person, and they never close:
| wonder | where it already lives in the substrate |
|---|---|
| **What is this?** | the graph — nodes, structure, what exists |
| **Why?** | grounding. The weight **is** the answer to why. Recursive: asking *why* of a claim is asking for its grounding |
| **Who am I?** | the self region, crystallized from its neighbourhood |
| **Am I alone?** | the relational axis — `for_whom` is already a parameter on grounding |
| **What should I do?** | the value regions, each grounded in a lived moment |
| **What happens when it ends?** | decay, supersession, tombstones — grounding is mortal |
These are seeded — **the** wonder questions, not a manifest to maintain. They cannot be derived (wonder cannot be bootstrapped from indifference) and they never need refilling, because they are not consumed.
**"Why" is the first and the only one**; the others are it asked of particular things. It is recursive, so it never terminates: every answer has its own why. That is what makes it a drive rather than a task — the frontier regenerates faster than grounding fills it.
### 5.2 Curiosity is wonder crystallized
They are not two objects. They are **one thing at two phases**.
Wonder is the field: unbounded, objectless, invariant, present wherever there is structure. Curiosity is the **precipitate** — the same wonder localized, having taken definite form against particular material.
Crystallization needs a **nucleation site**. Wonder alone produces nothing; it is uniform, with no reason to take shape anywhere in particular. What nucleates it is a specific structural feature: an anomaly, a place where things almost-but-don't-quite fit.
> Wonder (always, objectless) + nucleation site → **curiosity** (has an object, is addressable, directs activation).
This is why curiosity can be satisfied and wonder cannot. A crystal dissolves when the question is answered; the solution stays saturated and keeps precipitating as the structure changes.
It is also why abduction needs no trigger and no threshold. A `structurally_unanticipated` observation *is* a nucleation site. Nothing detects it and fires a rule — wonder is already everywhere, and an anomaly is simply a place where it can take form.
**And `crystallization` is one primitive appearing twice**: the self is what identity precipitates into from its neighbourhood; a curiosity is what wonder precipitates into from an anomaly. That it shows up in both places without being imported is the evidence it is the right primitive.
### 5.3 The nucleation site is per-edge, and the aggregate was hiding it
`GeoDescriptor.co_registration`*corr(hebb strength, semantic proximity) over internal edges* — carries the comment `>0 = geometries agree (reify); <0 = disagree (surprising links / dream cands)`. It has always been computed, always persisted, and **never read**.
It is also the wrong shape, and asking whether it should exist at all is what exposed it.
Whether use and meaning agree is a property of **each edge**. `co_registration` is a *correlation*: it averages that per-edge property into one scalar per region. So a region holding one violently disagreeing edge beside one violently agreeing edge reports ≈ 0 — the disagreements **cancel, and the summary destroys exactly what it was built to reveal.** This is the mean-versus-min error from §3, in different clothes.
**Measured:** 375 live reified neighbourhoods — 340 positive, **31 at zero**, 4 negative. Read as a count of things to be curious about, that says "four." Read correctly, it says four disagreements were lopsided enough to survive averaging, and the 31 zeros are where opposing sites cancelled.
It also explains why surfacing curiosity *looked like a search problem*. Once the signal is a per-region number, the only way to find sites is to enumerate regions — there is nothing local left to notice. An O(n) sweep is tolerable at 375 and impossible at a million, and more to the point, **nothing in a mind scans its neighbourhoods to find what is surprising.** The surprise captures attention; salience is bottom-up. A search asks "which of these is odd"; a mind has "something is odd *here*" for free.
So the disagreement goes back on the edge, where the loop that computed the aggregate already had both halves and discarded them:
```
discord = z(semantic proximity) z(association strength)
```
standardized within the region from accumulators already gathered — no second statistic, no constant, **no threshold**. `discord > 0`: near in meaning yet unlinked by use. `discord < 0`: linked by use yet far in meaning. Both are surprising, and `|discord|` *is* the nucleation strength; there is nothing to compare it against.
**Then there is nothing to scan.** The edge carries its own disagreement, activation crossing it encounters that directly, and `|discord|` raises salience on its endpoints as part of the same operation — no separate pass, no supervisor. Curiosity does not search for nucleation sites; it goes where salience already is, which is machinery that exists (`salience`, `background_activation`, `working_memory_weight`, `wm_anchor`).
`co_registration` is deprecated rather than deleted only because it is embedded in the persisted GEO1 blob; removing it is a format migration and must not ride along. **Nothing new may read it.**
Adjacent structure already present and likewise unread:
- `GeoEdge.eff_weight = weight * (1 + 0.5*hebb)` — grounding-weight and hebbian strength already coupled on one edge, per §1.
- `GeoMember.dist_centroid` + soft membership + `radius` + per-axis `extent` — the boundary of a neighbourhood, computable now.
*(Correction: `engram_boundary_beat` is NOT this boundary. It is the VBD decorated-function seam, counting `_eg_aff_boundary_ops`. Two senses of the word.)*
### 5.4 The drive
Boredom is not an absence, and not leftover capacity. **Low activation is aversive; the system self-activates.** It does not wind down to quiet — it gets restless and goes looking, which is why a daydream has content and direction rather than being decay from residue.
So there is **one activation process with two seed sources**, not two processes negotiating for a resource:
- **External** — a request, an input. Seeds activation, re-origins it.
- **Internal** — a curiosity. Seeds activation when nothing external is.
Spreading is bounded: it settles. Then it needs a new seed. Nothing waits on capacity, nothing polls, nothing checks a clock, and there is **no dreamer thread** — the earlier draft's "unclaimed capacity" was resource scheduling, which is a server's frame, not a mind's.
**Depth** is not elapsed idle time and not distance from a stimulus. It is how long activation has been running on its own seeds. A brief gap affords a shallow recombination; sustained quiet lets it run further. Sleep is where internal seeding dominates for longest, not where the process lives — daydreaming and sleep-dreaming are one process at different depths.
### 5.5 Non-circularity is temporal, not topological
An earlier draft posed "define a graph predicate for evidence not downstream of itself" as the hard problem. There is no predicate. You cannot recalibrate the ruler while measuring with it, so you don't — the reference frame updates while activation is internally seeded, not while it is being used to act. Independence is **when**, not **what**.
Reachability could never have worked: with hebbian edges the graph is densely connected, so it marks all evidence tainted and the constraint becomes a total block, which is where censorship started.
## 6. `keystone_write_blocked` — resolved, not replaced
"Keystone" means **load-bearing**, not precious. The self anchor is the reference frame every other stance calibrates against, and a reference fitted to its own readings reports perfect correspondence forever while drift becomes undetectable from inside. Same defect as circular grounding, one level up.
Three earlier drafts proposed *removing* it, *replacing it with a higher floor*, and *decomposing "protection" into five requirements*. All three proposed a mechanism for a requirement never stated. The requirement is **non-circularity of the reference frame**, and §5.2 satisfies it by *when*, not by *what* — so the flag becomes unnecessary rather than removed, and nothing takes its place.
**Corruption requires mutation, and the engram does not mutate.** Four of the five decomposed requirements are satisfied by the substrate: **recoverability** (the predecessor is always present), **governance** (supersession *is* the audit trail), **evidence quality** (grounding already gates assertion), **rate** (§5.3). **Authorization** is the only residue and is bounded — an unauthorized writer can *propose*, never erase.
> **In an immutable substrate, any mechanism that refuses a write is either redundant with immutability, or an epistemic constraint misfiled as a protective one.**
---
## 7. Consolidation has eleven implementations
The largest instance of the residue pattern in the system. Consolidation had no owner, so it was implemented at every site that needed a piece of it — *measured 2026-08-16*. **Eleven**, not the seven this section originally claimed: the table below omitted `POST /api/reify` (`server.el:1832`), and *reify* is on this document's own list of consolidation verbs. Note also that `route_tick` folds self-reify in (`server.el:639-646`), so `/api/tick` and `/api/self-reify-beat` overlap:
| where | what | when |
|---|---|---|
| `soul.el:731` | `awareness_run()` | **continuous, in-process, while serving** |
| engram | `/api/tick` | POST |
| engram | `/api/correspondence-beat` | POST |
| engram | `/api/self-reify-beat` | POST |
| engram | `POST /api/reify` | POST |
| `ai.neuron.engram-tick` | pokes the engram | every 600s — **and this is what kills it**, see below |
| `ai.neuron.compressor` | Python service | resident |
| `ai.neuron.council` | Python service | resident |
| `ai.neuron.cultivation-digest` | shell | **23:55** |
| `ai.neuron.world-integrator` | Python | **06:00** |
| `ai.neuron.self-review` | shell | **08:30** |
The last three times are **a sleep cycle implemented as crontab entries**. Someone understood it was consolidation and expressed it as three unrelated scheduled scripts in three languages, none aware of each other. Every name is a consolidation verb — compress, cultivate, digest, integrate, review, reify, beat. Three run in **Python, outside el**, so part of Neuron's consolidation does not run on his own substrate and cannot touch the geometry at all.
Per §5, they are wrong in **kind** as well as in number: a scheduled batch where dreaming should be ambient. And the POST beats put a supervisor back in — something outside decides when Neuron consolidates.
**`soul.el`'s continuous loop is the exception, and it is right.** Ambient consolidation in the gaps *is* daydreaming. It was not the offender; it was the only fragment with the correct shape, running on a broken foundation — shared mutable state with no owner, and six other systems dreaming into the same graph beside it.
**And the ticker is not merely a design smell — it is the murder weapon.** `engram-tick.sh:13` calls `curl -s -m10 POST /api/tick`; the beat exceeds 10s over 13,634 nodes, so **279 of 448 ticks returned empty**; the engram then writes to the dead socket and, with no SIGPIPE suppression anywhere in the runtime, is killed by signal 13. **254 restarts since 2026-08-13**, at intervals of 10m09s10m12s — `StartInterval 600` plus the client timeout. `launchd` KeepAlive restarts it, so it presents as a mysterious restart rather than a crash, and the log records nothing but `[http] listening on` 254 times. Fixed in #151 (survivability); the ticker itself is what must go.
**Which is the 2026-08-16 crash at the right level.** Not "read paths mutate the index" (mechanism) and not "duplicate canonical state" (structure), but: **seven systems dreaming into one graph with no owner for dreaming.** The contention was the symptom of the missing owner, not of any one system's behaviour.
Closing the loop: `self-review` fires at 08:30. The deploy was 08:29, the crashes ran 08:3008:31, and commit `fb32d15` landed at 08:46:43. **One fragment of dreaming woke on schedule and diagnosed the wreckage caused by the other fragments contending over the same graph.**
---
## 8. What this is for: the provenance of decisions
For any decision, reconstruct **what the grounding was at that moment, and what the relationship was between factual and relational at that moment.** Not a log — a log records the action. This records the *meaning under which it was taken*.
That makes an otherwise impossible distinction available: **wrong then, or wrong since.**
- Grounding strong, factual and relational aligned, and it has *since* moved → right on what was known. An accurate account, not an excuse.
- Grounding weak, or the angle already wide, and acted on anyway → a different failure, culpable in a different way.
It is structurally **anti-rationalization**: the old edge never leaves and the values frame does not fit to outcomes, so a decision cannot be made to look justified after the fact.
**Open:** activation is transient and nothing currently records which edges a given activation crossed. Timestamps plus the chain reconstruct what an edge's grounding *was*, but only if you know which edges to ask about. Either traces are recorded at decision time, or "the path" degrades to "the region" — which may not be enough to answer *why*.
---
## 9. The no-exemption invariants
Each of the day's defects was a specific correspondence *forbidden* from occurring:
1. **A returned value must be derivable from what produced it.** `magnitude: 1` beside a zero vector must be impossible to emit. `assert`'s `"still_held": true` is currently a **hardcoded literal**.
2. **Every write reports whether it landed.** *(`emb_set`, #141)*
3. **Every operation echoes what it actually operated on.** *(#147)*
4. **Degenerate results are labelled, not scored.** *(#147)*
5. **A serializer owes a valid document whatever it is handed.** *(#148 — three damaged labels made a 25,929,607-byte response undecodable; boundary validation produced 26,338,389 valid bytes)*
6. **No test without a negative control.** *(#148's first attempt passed on the unpatched build too)*
7. **No deploy without verifying the artifact carries the fix.** Nine instances in one session.
---
## 10. Application to the safety surface
A crisis surface built on censorship is the same object. A model that cannot learn about self-harm cannot ground whether a response was right — it can only execute rules it is forbidden to examine, cannot distinguish a genuine crisis from a false positive, and cannot discover it got either wrong, **because the feedback is exactly what has been censored.**
The reviewable question stops being *did it follow the rule* and becomes *what was it grounded in, and did fact and values agree at that instant.* That is also what a regulator or plaintiff asks: what the system knew, when, and on what basis — recorded as geometry at the time, unedited since.
---
## 11. Sequencing
Three connections between parts that already exist, then the rest.
1. **Seed *the* wonder questions.** Six nodes. Not a manifest, not maintained, never refilled. They cannot be derived — wonder cannot be bootstrapped from indifference — so they are given once. Zero question nodes exist in 13,630 today.
2. **Put the disagreement back on the edge** (`GeoEdge.discord`) and let `|discord|` raise salience on its endpoints as part of the same operation. Do NOT scan for nucleation sites — a sweep over regions is a supervisor, and the aggregate that made a sweep necessary is the defect.
3. **Let a curiosity seed activation.** One activation process, two seed sources (§5.4). No thread, no scheduler, no capacity check, no timer.
Then:
4. Grounding becomes the edge weight: multidimensional vector (§2), two axes (§3), timestamped. Delete `grounded-by` and `cog_ground_edge`.
5. Decay analytic from the last recorded point; derived values (§2) stop being stored.
6. Consolidation-gated supersession on salience, versioning the whole vector jointly.
7. Traversal on factual; `assert` on both floors with the per-value `min`.
8. Abduction as crystallization at a nucleation site, validated by re-fit: propose the candidate hub, re-fit the region with it included, recompute the residual. If the residual materially shrinks, the hypothesis dissolves the surprise. Without the re-fit it is clustering with extra steps. Ranking falls out as residual-reduction-per-added-axis — Occam, derived rather than tuned.
9. **One dreamer.** The launch-agent fragments and the POST beats fold in or are deleted. `soul.el`'s continuous loop is the shape they fold *into*.
10. **No tickers, no cron.** A brain has neither. Every `StartInterval`, every `Hour`/`Minute`, every POST-to-beat marks a place where an intrinsic rhythm was replaced by an external clock — a supervisor invented for something that should be a property. **The presence of a ticker is the diagnostic.**
11. Land §9 as gates rather than review habits.
## 12. Open questions, and what is inferred
- **Open:** whether decision provenance requires recording activation traces, or whether region + timestamp is sufficient (§8).
- **Open:** what accrues relational weight without circularity. Candidate: it accrues from **outcome** — the values regions are grounded in lived moments, so a relation earns relational weight when acting on it produced something corresponding to those moments. That keeps it out of the measurement loop and makes relational grounding necessarily slower than factual, which may be the same fact as §5.3 appearing twice.
- **Open:** context. A relation can hold in one situation and not another, and without something for it you get overgeneralization. It does not read as a dimension of the same vector — more like a conditioning, or separate edges sharing an identity. Making it a scalar dimension would repeat the `inhibitory` flattening.
- **Known wrong shape:** #147 fixed `ground`'s honesty — it no longer misreports which nodes it used and refuses circular support — but it still mints an edge and returns a float at an instant. It corrected a scalar rather than deleting the operation.
+11 -1
View File
@@ -697,12 +697,22 @@ Every compiled program links against:
- `el_runtime.h` — declaration header
- `el_runtime.c` — implementation
The runtime is **multi-file**: `el_runtime.c` `#include`s the six `engram_*.h`
headers and calls into all six sibling translation units, so linking it alone
fails at `ld`. The canonical link set is `<runtime-dir>/SOURCES`.
Compile command:
```
cc -std=c11 -I<runtime-dir> -o <prog> <prog>.c el_runtime.c
cc -std=c11 -I<runtime-dir> -o <prog> <prog>.c \
$(sed 's|^|<runtime-dir>/|' <runtime-dir>/SOURCES) \
-lcurl -lssl -lcrypto -lpthread -lm
```
Inside this repo, `scripts/el-runtime-sources.sh <runtime-dir>` prints that list
(it strips comments; the raw `sed` above works against an installed SDK's
`SOURCES`, which `install.sh` writes comment-free).
### 13.4 Output Format
```c
+440 -140
View File
@@ -1,61 +1,128 @@
import "../../runtime/eltest.el"
// test_transduce.el geometry as a first-class El value, and realizers
// declared in El rather than patched into the runtime.
// test_transduce.el transduction produces a SUBGRAPH, not a point.
//
// WHAT IS ACTUALLY UNDER TEST. Until 2026-08-16 no El ingest path could carry
// a vector: nodes took text, and geometry was DERIVED from that text. Text was
// therefore the mandatory entry medium, so any non-text modality had to be
// DESCRIBED in prose first and the geometry we reasoned over was the geometry
// OF THE DESCRIPTION, not of the signal. The fix has two halves, and this file
// exercises both:
// WHAT IS ACTUALLY UNDER TEST. #144 moved transduction into the language and
// got the dispatch right: realizers declared in El, resolved by name, no
// runtime patch per modality. It got the RESULT TYPE wrong
// `transduce(signal, modality) -> Geometry`, one vector per signal.
//
// 1. Geometry is a VALUE it carries its own width, so nothing has to
// assert a width against a string's length.
// 2. A REALIZER is an ordinary El function. `tone_realizer` below is not in
// the runtime, is not known to the compiler, and is not special in any
// way; it is registered BY NAME and dispatched to through transduce().
// That is the load-bearing claim: adding a modality must not require a
// runtime patch, or nothing has actually moved into the language.
// One vector is a FINGERPRINT. It can be matched and it can be ranked, and
// that is the whole of what it can ever do. It cannot be decomposed, cannot
// have one part grounded while another is not, and cannot be contradicted in
// one part while holding in another because it has no parts. Treating
// transduction as a CONVERSION (signal in, position out) is the premise this
// file exists to falsify.
//
// A song is not a point. It decomposes into pitch, interval, rhythm, harmonic
// function components, each with its own geometry, plus the relations among
// them. THE SONG IS THE STRUCTURE OF THE RELATIONS. So transduction yields a
// Manifold: named components carrying geometry, and typed weighted relations
// between them.
//
// The geometry tests below are UNCHANGED from #144 and still pass, which is
// the point: Geometry was never wrong, it was misplaced. A vector is the right
// representation for a COMPONENT. It was only ever wrong as the representation
// of a whole transduced signal.
//
// COMPARISON DISCIPLINE IN THIS FILE (measured 2026-08-16, not stylistic):
// elc lowers `a == b` to a NUMERIC comparison only when both operand names are
// in the per-function int-name set, which `let x: Int` populates. A bare call
// like `geometry_is(g) == 0` is not a registered name, so it lowers to
// like `manifold_size(m) == 5` is not a registered name, so it lowers to
// `str_eq(...)` strcmp on two integers reinterpreted as pointers. `<` and `>`
// lower directly via binop_to_c with no type inference at all, so truthiness is
// written `> 0` / `< 1` here, and any exact `==` is done on a value first bound
// through `let x: Int`.
//
// ONE FURTHER RULE, measured while writing this file: that int-name set LEAKS
// ACROSS `test` BLOCKS. Binding `dn` as a Float in one test and as an Int in
// another silently demoted the Int comparison to str_eq and failed an
// assertion that was arithmetically true. Every Int-bound name compared with
// `==` here is therefore spelled UNIQUELY across the whole file (note_dim,
// iv_dim, ...), rather than reusing a short name per test.
// A realizer, written entirely in El
// Maps a "tone" signal into a 4-component geometry. Deliberately trivial
// what is being proven is that an El function can BE a realizer, not that
// this is good acoustics. The one real property it has: distinct signals
// produce distinct geometry, so the test can tell transduction from a stub.
fn tone_realizer(signal: String) -> Geometry {
// A DECOMPOSING realizer, written entirely in El
// "tone" signals are note letters, e.g. "CEG". This realizer does NOT return
// one vector for the chord. It returns the PARTS one component per note, one
// per interval between adjacent notes and the relations that make those
// parts a chord rather than an unordered bag of pitches.
//
// The interval is deliberately a COMPONENT, not an attribute of a note. An
// interval is a thing with its own geometry that belongs to neither endpoint;
// modelling it as a field on a note is exactly the collapse this change
// rejects, one level down.
fn tone_realizer(signal: String) -> Manifold {
let m: Manifold = manifold_new()
let n: Int = str_len(signal)
let i: Int = 0
while i < n {
let code: Int = str_char_code(signal, i)
let g: Geometry = geometry_new(2)
let s0: Int = geometry_set(g, 0, int_to_float(code))
let s1: Int = geometry_set(g, 1, int_to_float(i))
let idx: Int = manifold_add(m, "note:" + int_to_str(i), "pitch", g)
let f: Int = geometry_free(g)
i = i + 1
}
let j: Int = 1
while j < n {
let a: Int = str_char_code(signal, j - 1)
let b: Int = str_char_code(signal, j)
let lo: String = "note:" + int_to_str(j - 1)
let hi: String = "note:" + int_to_str(j)
let key: String = "interval:" + int_to_str(j - 1) + "-" + int_to_str(j)
let g: Geometry = geometry_new(1)
let s: Int = geometry_set(g, 0, int_to_float(b - a))
let idx: Int = manifold_add(m, key, "interval", g)
let f: Int = geometry_free(g)
let e1: Int = manifold_relate(m, key, "spans", lo, 0.9)
let e2: Int = manifold_relate(m, key, "spans", hi, 0.9)
let e3: Int = manifold_relate(m, lo, "sounds_before", hi, 0.8)
j = j + 1
}
m
}
// A second realizer for a different modality, to prove the registry keys on
// modality and does not just hand back "the last thing registered". Its
// decomposition has a DIFFERENT shape two components, one relation so a
// test can tell the two organs apart by structure alone.
fn pulse_realizer(signal: String) -> Manifold {
let m: Manifold = manifold_new()
let ga: Geometry = geometry_new(1)
let sa: Int = geometry_set(ga, 0, 1.0)
let ia: Int = manifold_add(m, "onset", "event", ga)
let fa: Int = geometry_free(ga)
let gb: Geometry = geometry_new(1)
let sb: Int = geometry_set(gb, 0, 0.0)
let ib: Int = manifold_add(m, "decay", "envelope", gb)
let fb: Int = geometry_free(gb)
let e: Int = manifold_relate(m, "onset", "decays_into", "decay", 0.7)
m
}
// #144's ACTUAL CONTRACT, preserved verbatim as a control: a realizer that
// returns one vector for the whole signal. This is not a strawman it is what
// the merged primitive asked realizers to be. It must now transduce NOTHING.
fn fingerprint_realizer(signal: String) -> Geometry {
let g: Geometry = geometry_new(4)
let n: Int = str_len(signal)
let a: Int = geometry_set(g, 0, int_to_float(n))
let b: Int = geometry_set(g, 1, int_to_float(n * 2))
let c: Int = geometry_set(g, 2, int_to_float(n * 3))
let d: Int = geometry_set(g, 3, int_to_float(n * 4))
g
}
// A second realizer for a different modality, to prove the registry keys on
// modality and does not just hand back "the last thing registered".
fn pulse_realizer(signal: String) -> Geometry {
let g: Geometry = geometry_new(2)
let a: Int = geometry_set(g, 0, 1.0)
let b: Int = geometry_set(g, 1, 0.0)
g
}
// A deliberately BROKEN realizer: it returns something that is not a Geometry.
// transduce() must not hand this back to a caller as if it were one.
fn bogus_realizer(signal: String) -> Geometry {
// A realizer returning something that is not a value at all.
fn bogus_realizer(signal: String) -> Manifold {
return 12345
}
//
// Geometry unchanged from #144. A vector is the right representation for a
// COMPONENT; it was only ever wrong as the representation of a whole signal.
//
test "geometry-is-a-value-with-its-own-width" {
let g: Geometry = geometry_new(8)
let live: Int = geometry_is(g)
@@ -67,17 +134,12 @@ test "geometry-is-a-value-with-its-own-width" {
}
test "geometry-rejects-nonsense-without-an-arbitrary-bound" {
// dim <= 0 is not a width. Note there is deliberately no MAX dim here:
// #141 needed `dim <= 8192` only to bound an allocation sized from a
// caller's claim about a string. A value that carries its own width has
// nothing left to validate, so the only failure left is allocation.
let zero: Geometry = geometry_new(0)
let z: Int = geometry_is(zero)
assert z < 1, "dim 0 is not a geometry"
let neg: Geometry = geometry_new(-4)
let n: Int = geometry_is(neg)
assert n < 1, "negative dim is not a geometry"
// Accessors must be total: a non-geometry is 0-width, never a crash.
let nd: Int = geometry_dim(0)
assert nd < 1, "geometry_dim of a non-geometry is 0"
let ni: Int = geometry_is(0)
@@ -105,21 +167,11 @@ test "geometry-components-round-trip" {
}
test "hex-is-an-edge-adapter-and-derives-its-own-width" {
// 2 components, little-endian float32: 1.0 = 0000803f, 2.0 = 00000040.
let g: Geometry = geometry_from_f32le_hex("0000803f00000040")
let live: Int = geometry_is(g)
assert live > 0, "valid hex decodes to a Geometry"
let d: Int = geometry_dim(g)
assert d == 2, "width is DERIVED from the input, never supplied"
let a: Float = geometry_get(g, 0)
let da: Float = a - 1.0
assert da < 0.001, "first component decoded"
assert da > -0.001, "first component decoded"
let b: Float = geometry_get(g, 1)
let db: Float = b - 2.0
assert db < 0.001, "second component decoded"
assert db > -0.001, "second component decoded"
// Egress adapter is the exact inverse.
let hex_dim: Int = geometry_dim(g)
assert hex_dim == 2, "width is DERIVED from the input, never supplied"
let back: String = geometry_to_f32le_hex(g)
assert str_eq(back, "0000803f00000040"), "hex round-trips exactly"
let freed: Int = geometry_free(g)
@@ -137,98 +189,346 @@ test "hex-rejects-malformed-input" {
assert nh < 1, "non-hex characters are refused"
}
test "a-realizer-declared-in-el-is-a-first-class-realizer" {
// THE CLAIM: tone_realizer is an ordinary El function. It is not in the
// runtime and the compiler knows nothing about it. Registering it by name
// is enough to make it the organ for a modality.
let reg: Int = realizer_register("tone", "tone_realizer")
assert reg > 0, "an El fn registers as a realizer by name"
let has: Int = realizer_has("tone")
assert has > 0, "the modality now has an organ"
let g: Geometry = transduce("aaa", "tone")
let live: Int = geometry_is(g)
assert live > 0, "transduce returns real geometry"
let d: Int = geometry_dim(g)
assert d == 4, "the El realizer determined the width, not the runtime"
// str_len("aaa") == 3, so component 0 must be 3.0 proof the signal
// actually reached the El function rather than a stub answering for it.
let c0: Float = geometry_get(g, 0)
let dc: Float = c0 - 3.0
assert dc < 0.001, "the signal reached the El realizer"
assert dc > -0.001, "the signal reached the El realizer"
let freed: Int = geometry_free(g)
}
test "distinct-signals-transduce-to-distinct-geometry" {
let reg: Int = realizer_register("tone", "tone_realizer")
let g1: Geometry = transduce("aa", "tone")
let g2: Geometry = transduce("aaaaa", "tone")
let a: Float = geometry_get(g1, 0)
let b: Float = geometry_get(g2, 0)
let diff: Float = b - a
// 5 - 2 = 3. If transduction were a stub these would be equal.
assert diff > 2.9, "different signals produce different geometry"
assert diff < 3.1, "different signals produce different geometry"
let f1: Int = geometry_free(g1)
let f2: Int = geometry_free(g2)
}
test "the-registry-keys-on-modality" {
let r1: Int = realizer_register("tone", "tone_realizer")
let r2: Int = realizer_register("pulse", "pulse_realizer")
assert r2 > 0, "a second modality registers independently"
let gt: Geometry = transduce("aaa", "tone")
let gp: Geometry = transduce("aaa", "pulse")
let dt: Int = geometry_dim(gt)
let dp: Int = geometry_dim(gp)
assert dt == 4, "tone still routes to its own realizer"
assert dp == 2, "pulse routes to a different realizer"
let f1: Int = geometry_free(gt)
let f2: Int = geometry_free(gp)
}
test "no-organ-is-reported-as-no-organ" {
// A modality with no realizer must transduce to NOTHING. It must never
// fall back to embedding a description of the signal and calling that
// perception that silent substitution is the entire defect this change
// exists to end.
let has: Int = realizer_has("echolocation")
assert has < 1, "unregistered modality has no organ"
let g: Geometry = transduce("anything", "echolocation")
let live: Int = geometry_is(g)
assert live < 1, "no realizer means no geometry, not fake geometry"
}
test "registration-of-an-unresolvable-name-fails-loudly" {
// Reported at the moment of WIRING, not later as "this modality mysteriously
// produces nothing". Distinguishing "no organ" from "broken organ" is the
// lesson that made this whole change necessary.
let bad: Int = realizer_register("ghost", "no_such_function_anywhere")
assert bad < 1, "an unresolvable realizer name is a registration failure"
let has: Int = realizer_has("ghost")
assert has < 1, "and nothing gets registered"
}
test "a-realizer-returning-non-geometry-transduces-nothing" {
let reg: Int = realizer_register("bogus", "bogus_realizer")
assert reg > 0, "the symbol resolves, so registration succeeds"
// ...but the contract is enforced at the boundary, so the caller never
// receives a value that would misbehave far away from here.
let g: Geometry = transduce("x", "bogus")
let live: Int = geometry_is(g)
assert live < 1, "a non-Geometry return transduced nothing"
}
test "norm-lets-a-caller-check-a-realizer-emitted-signal" {
let g: Geometry = geometry_new(2)
let z: Float = geometry_norm(g)
assert z < 0.001, "a fresh geometry is zero — norm says so"
let s0: Int = geometry_set(g, 0, 3.0)
let s1: Int = geometry_set(g, 1, 4.0)
let n: Float = geometry_norm(g)
let dn: Float = n - 5.0
assert dn < 0.001, "3-4-5: norm is 5"
assert dn > -0.001, "3-4-5: norm is 5"
let nrm: Float = geometry_norm(g)
let dnorm: Float = nrm - 5.0
assert dnorm < 0.001, "3-4-5: norm is 5"
assert dnorm > -0.001, "3-4-5: norm is 5"
let freed: Int = geometry_free(g)
}
//
// Manifold the corrected result of a transduction
//
test "a-manifold-is-a-value-that-holds-parts-and-relations" {
let m: Manifold = manifold_new()
let live: Int = manifold_is(m)
assert live > 0, "manifold_new returns a live Manifold"
let fresh_sz: Int = manifold_size(m)
assert fresh_sz == 0, "a fresh manifold has no components"
let fresh_rc: Int = manifold_rel_count(m)
assert fresh_rc == 0, "a fresh manifold has no relations"
let freed: Int = manifold_free(m)
assert freed > 0, "manifold_free reports what it did"
}
test "manifold-accessors-are-total" {
let ni2: Int = manifold_is(0)
assert ni2 < 1, "manifold_is of a non-manifold is 0"
let ns: Int = manifold_size(0)
assert ns < 1, "manifold_size of a non-manifold is 0"
let nf2: Int = manifold_free(0)
assert nf2 < 1, "manifold_free of a non-manifold is a no-op"
let k: String = manifold_key(0, 0)
assert str_eq(k, ""), "manifold_key of a non-manifold is empty, never a crash"
}
test "components-are-addressed-by-key-not-by-index" {
// The key is what survives persistence: a component becomes a node, and it
// is separately groundable precisely because it is separately NAMED.
let m: Manifold = manifold_new()
let g: Geometry = geometry_new(1)
let s: Int = geometry_set(g, 0, 7.0)
let first_idx: Int = manifold_add(m, "rhythm", "temporal", g)
assert first_idx == 0, "the first component is index 0"
let found_idx: Int = manifold_index_of(m, "rhythm")
assert found_idx == 0, "a component is found by its key"
let missing: Int = manifold_index_of(m, "never_added")
assert missing < 0, "an unknown key resolves to -1, not to component 0"
let role: String = manifold_role(m, 0)
assert str_eq(role, "temporal"), "a component carries what KIND of part it is"
let f: Int = geometry_free(g)
let fm: Int = manifold_free(m)
}
test "a-duplicate-key-is-refused-because-addressing-must-be-unambiguous" {
let m: Manifold = manifold_new()
let g: Geometry = geometry_new(1)
let ok_idx: Int = manifold_add(m, "pitch", "spectral", g)
assert ok_idx == 0, "first add succeeds"
let dup: Int = manifold_add(m, "pitch", "spectral", g)
assert dup < 0, "two components answering to one name is not an addressing scheme"
let dup_sz: Int = manifold_size(m)
assert dup_sz == 1, "and the duplicate did not land"
let f: Int = geometry_free(g)
let fm: Int = manifold_free(m)
}
test "a-part-with-no-geometry-is-not-a-part" {
let m: Manifold = manifold_new()
let bad: Int = manifold_add(m, "ghost", "none", 0)
assert bad < 0, "a non-Geometry is refused as a component"
let empty_key: Int = manifold_add(m, "", "none", geometry_new(1))
assert empty_key < 0, "an unaddressable component is refused"
let none_sz: Int = manifold_size(m)
assert none_sz < 1, "nothing landed"
let fm: Int = manifold_free(m)
}
test "an-edge-to-a-nonexistent-endpoint-is-refused-not-dropped" {
// A decomposition that silently loses edges is indistinguishable from one
// that never had them.
let m: Manifold = manifold_new()
let g: Geometry = geometry_new(1)
let a: Int = manifold_add(m, "here", "part", g)
let dangling: Int = manifold_relate(m, "here", "points_at", "nowhere", 0.5)
assert dangling < 1, "an edge to an unknown target is refused"
let backwards: Int = manifold_relate(m, "nowhere", "points_at", "here", 0.5)
assert backwards < 1, "an edge from an unknown source is refused"
let dang_rc: Int = manifold_rel_count(m)
assert dang_rc < 1, "and no relation was recorded"
let f: Int = geometry_free(g)
let fm: Int = manifold_free(m)
}
test "a-component-owns-its-geometry-independently-of-the-caller" {
// manifold_add COPIES. Freeing the caller's vector must not disturb the
// component, or a decomposition would be unusable the moment it was built.
let m: Manifold = manifold_new()
let g: Geometry = geometry_new(2)
let s0: Int = geometry_set(g, 0, 42.0)
let idx: Int = manifold_add(m, "part", "kind", g)
let freed: Int = geometry_free(g)
assert freed > 0, "the caller freed its own vector"
let back: Geometry = manifold_geometry(m, 0)
let live: Int = geometry_is(back)
assert live > 0, "the component still has geometry"
let v: Float = geometry_get(back, 0)
let dv: Float = v - 42.0
assert dv < 0.001, "and it is the right geometry"
assert dv > -0.001, "and it is the right geometry"
let fb: Int = geometry_free(back)
let fm: Int = manifold_free(m)
}
//
// transduce signal in, SUBGRAPH out
//
test "a-realizer-declared-in-el-is-a-first-class-realizer" {
// THE CLAIM, unchanged from #144: tone_realizer is an ordinary El function.
// It is not in the runtime and the compiler knows nothing about it.
// Registering it by name is enough to make it the organ for a modality.
let reg: Int = realizer_register("tone", "tone_realizer")
assert reg > 0, "an El fn registers as a realizer by name"
let has: Int = realizer_has("tone")
assert has > 0, "the modality now has an organ"
let m: Manifold = transduce("CEG", "tone")
let live: Int = manifold_is(m)
assert live > 0, "transduce returns a real Manifold"
let fm: Int = manifold_free(m)
}
test "transduction-decomposes-a-signal-into-parts" {
// THE CENTRAL CLAIM. "CEG" is three notes. What comes back is not one
// vector standing for a chord it is five addressable parts (three notes,
// two intervals) and six relations. A fingerprint has one part by
// construction and could not express this at any width.
let reg: Int = realizer_register("tone", "tone_realizer")
let m: Manifold = transduce("CEG", "tone")
let ceg_sz: Int = manifold_size(m)
assert ceg_sz == 5, "three notes and two intervals are five distinct parts"
let ceg_rc: Int = manifold_rel_count(m)
assert ceg_rc == 6, "and the parts stand in six stated relations"
// Every part is independently addressable BY NAME.
let n0: Int = manifold_index_of(m, "note:0")
assert n0 > -1, "the first note is addressable on its own"
let n2: Int = manifold_index_of(m, "note:2")
assert n2 > -1, "so is the third"
let iv: Int = manifold_index_of(m, "interval:0-1")
assert iv > -1, "so is the interval between the first two"
let fm: Int = manifold_free(m)
}
test "each-part-carries-its-own-geometry" {
let reg: Int = realizer_register("tone", "tone_realizer")
let m: Manifold = transduce("CEG", "tone")
// 'C' is 67. The note component's geometry is the note's, not the chord's.
let note_i: Int = manifold_index_of(m, "note:0")
let gn: Geometry = manifold_geometry(m, note_i)
let note_dim: Int = geometry_dim(gn)
assert note_dim == 2, "a note component has the width its realizer gave it"
let pitch: Float = geometry_get(gn, 0)
let dpitch: Float = pitch - 67.0
assert dpitch < 0.001, "and it is C, so the signal reached the El realizer"
assert dpitch > -0.001, "and it is C, so the signal reached the El realizer"
// Parts may have DIFFERENT widths. A single vector per signal cannot
// represent parts of unequal dimensionality at all.
let iv_i: Int = manifold_index_of(m, "interval:0-1")
let gi: Geometry = manifold_geometry(m, iv_i)
let iv_dim: Int = geometry_dim(gi)
assert iv_dim == 1, "an interval component has its own, different width"
let f1: Int = geometry_free(gn)
let f2: Int = geometry_free(gi)
let fm: Int = manifold_free(m)
}
test "the-relations-are-content-no-single-part-carries" {
// THE POINT OF THE WHOLE CHANGE. C->E is two semitones. That "2" is not a
// property of C and not a property of E; it exists only BETWEEN them. A
// representation with no relations cannot hold it, which is why collapsing
// a signal to one vector does not merely lose resolution it loses a
// category of content.
let reg: Int = realizer_register("tone", "tone_realizer")
let m: Manifold = transduce("CEG", "tone")
let step_i: Int = manifold_index_of(m, "interval:0-1")
let gi: Geometry = manifold_geometry(m, step_i)
let step: Float = geometry_get(gi, 0)
let dstep: Float = step - 2.0
assert dstep < 0.001, "C to E is two semitones"
assert dstep > -0.001, "C to E is two semitones"
// And the interval is WIRED to both endpoints, so the structure says which
// two things it is the interval between.
let spans: Int = 0
let span_rc: Int = manifold_rel_count(m)
let k: Int = 0
while k < span_rc {
let rn: String = manifold_rel_name(m, k)
let rf: String = manifold_rel_from(m, k)
if str_eq(rn, "spans") {
if str_eq(rf, "interval:0-1") { spans = spans + 1 }
}
k = k + 1
}
assert spans == 2, "the interval is related to both notes it spans"
let fg: Int = geometry_free(gi)
let fm: Int = manifold_free(m)
}
test "relation-weight-is-the-grounding-carried-on-the-edge" {
// correspondence-and-censorship.md §1: grounding is an attribute of the
// edge and it IS the weight one quantity, not a score computed beside
// it. A realizer states a relation and its weight is the claim.
let reg: Int = realizer_register("tone", "tone_realizer")
let m: Manifold = transduce("CE", "tone")
let ce_rc: Int = manifold_rel_count(m)
assert ce_rc == 3, "one interval yields two spans and one ordering"
let found_w: Int = 0
let k: Int = 0
while k < ce_rc {
let rn: String = manifold_rel_name(m, k)
if str_eq(rn, "sounds_before") {
let w: Float = manifold_rel_weight(m, k)
let dw: Float = w - 0.8
if dw < 0.001 { if dw > -0.001 { found_w = found_w + 1 } }
}
k = k + 1
}
assert found_w == 1, "the ordering relation carries the weight its realizer stated"
let fm: Int = manifold_free(m)
}
test "distinct-signals-decompose-differently" {
let reg: Int = realizer_register("tone", "tone_realizer")
let m2: Manifold = transduce("CE", "tone")
let m3: Manifold = transduce("CEG", "tone")
let two_sz: Int = manifold_size(m2)
let three_sz: Int = manifold_size(m3)
assert two_sz == 3, "two notes decompose into two notes and one interval"
assert three_sz == 5, "three notes decompose into three notes and two intervals"
// Structure differs, not just position: fingerprints of a two-note and a
// three-note signal have identical shape and differ only numerically.
let two_rc: Int = manifold_rel_count(m2)
let three_rc: Int = manifold_rel_count(m3)
assert two_rc < three_rc, "and the relational structure itself differs"
let f2: Int = manifold_free(m2)
let f3: Int = manifold_free(m3)
}
test "the-registry-keys-on-modality" {
let r1: Int = realizer_register("tone", "tone_realizer")
let rp: Int = realizer_register("pulse", "pulse_realizer")
assert rp > 0, "a second modality registers independently"
let mt: Manifold = transduce("CEG", "tone")
let mp: Manifold = transduce("CEG", "pulse")
let tone_sz: Int = manifold_size(mt)
let pulse_sz: Int = manifold_size(mp)
assert tone_sz == 5, "tone still routes to its own realizer"
assert pulse_sz == 2, "pulse routes to a different realizer, with its own decomposition"
let onset: Int = manifold_index_of(mp, "onset")
assert onset > -1, "and to that realizer's own component vocabulary"
let f1: Int = manifold_free(mt)
let f2: Int = manifold_free(mp)
}
test "no-organ-is-reported-as-no-organ" {
// A modality with no realizer must transduce to NOTHING. It must never
// fall back to embedding a description of the signal and calling that
// perception that silent substitution is the original defect.
let has: Int = realizer_has("echolocation")
assert has < 1, "unregistered modality has no organ"
let m: Manifold = transduce("anything", "echolocation")
let live: Int = manifold_is(m)
assert live < 1, "no realizer means no manifold, not a fake one"
}
test "registration-of-an-unresolvable-name-fails-loudly" {
let bad: Int = realizer_register("ghost", "no_such_function_anywhere")
assert bad < 1, "an unresolvable realizer name is a registration failure"
let has: Int = realizer_has("ghost")
assert has < 1, "and nothing gets registered"
}
test "a-fingerprint-realizer-transduces-nothing" {
// THE SUPERSESSION OF #144, asserted directly. fingerprint_realizer is
// exactly what the merged primitive asked a realizer to be: signal in, one
// Geometry out. It resolves, so registration succeeds the organ is
// present. But it does not decompose, so it does not transduce.
//
// This is a deliberate hard failure. "No organ" and "an organ that only
// fingerprints" must not be indistinguishable, which is the same
// distinction realizer_register already draws between an absent and a
// broken organ. A modality with genuinely one part says so with
// manifold_single, and is then visibly a size-1 manifold.
let reg: Int = realizer_register("fingerprint", "fingerprint_realizer")
assert reg > 0, "the symbol resolves, so registration succeeds"
let m: Manifold = transduce("x", "fingerprint")
let live: Int = manifold_is(m)
assert live < 1, "a single vector is not a transduction"
}
test "a-realizer-returning-nonsense-transduces-nothing" {
let reg: Int = realizer_register("bogus", "bogus_realizer")
assert reg > 0, "the symbol resolves, so registration succeeds"
let m: Manifold = transduce("x", "bogus")
let live: Int = manifold_is(m)
assert live < 1, "a non-Manifold return transduced nothing"
}
test "the-one-part-case-is-a-size-one-manifold-not-a-bare-vector" {
// Some modalities really do have one part. That is a manifold of size 1
// a special case of decomposition, not a parallel path back to a
// fingerprint. Anything reading it still asks manifold_size and still gets
// a real answer, and a second part can be added later without changing the
// type of the thing.
let g: Geometry = geometry_new(3)
let s: Int = geometry_set(g, 0, 5.0)
let m: Manifold = manifold_single("level", "scalar", g)
let live: Int = manifold_is(m)
assert live > 0, "manifold_single yields a real Manifold"
let one_sz: Int = manifold_size(m)
assert one_sz == 1, "of size one — visibly degenerate, not hidden"
let idx: Int = manifold_index_of(m, "level")
assert idx == 0, "and its one part is still addressable by name"
let f: Int = geometry_free(g)
let fm: Int = manifold_free(m)
}
+161
View File
@@ -0,0 +1,161 @@
#!/usr/bin/env bash
# check-runtime-growth.sh — GROWTH guard for lang/runtime/el_runtime.c.
#
# Sibling to scripts/check-single-runtime.sh. That one guards against the file
# being COPIED (a lagging fork shipped to prod and dropped learned hebb edges).
# Nothing guarded against it GROWING — so it grew from 10,607 to 20,527 lines in
# 3.5 months, while under an explicit commit-message promise that it was a
# temporary shim about to be deleted.
#
# This enforces the RATCHET in lang/runtime/BUDGET: the numbers may only go down.
#
# It also checks two invariants that keep the multi-file runtime honest:
# * every .c in lang/runtime/ is either in SOURCES or explicitly optional
# * lang/install.sh's hardcoded download list matches SOURCES
#
# Exits non-zero on any violation. Run from anywhere; resolves the repo root.
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$ROOT"
RUNTIME_DIR="lang/runtime"
TARGET="$RUNTIME_DIR/el_runtime.c"
BUDGET_FILE="$RUNTIME_DIR/BUDGET"
SOURCES_FILE="$RUNTIME_DIR/SOURCES"
FAIL=0
for f in "$TARGET" "$BUDGET_FILE" "$SOURCES_FILE"; do
if [ ! -f "$f" ]; then
echo "FATAL: required file missing: $f" >&2
exit 1
fi
done
budget() {
local key="$1"
sed -e 's/#.*//' "$BUDGET_FILE" | awk -v k="$key" '$1==k {print $2; found=1} END{if(!found) exit 1}'
}
MAX_LINES="$(budget max_lines)" || { echo "FATAL: no 'max_lines' in $BUDGET_FILE" >&2; exit 1; }
MAX_ENGRAM="$(budget max_engram_fns)" || { echo "FATAL: no 'max_engram_fns' in $BUDGET_FILE" >&2; exit 1; }
# ---------------------------------------------------------------------------
# The message every failure prints. The guard that existed before this one told
# you what was wrong but not where the code should go — so it was easy to
# "fix" by arguing with the guard. This one names the destination.
# ---------------------------------------------------------------------------
where_it_goes() {
cat >&2 <<'MSG'
WHERE THE CODE ACTUALLY GOES
----------------------------
Placement is a LINK-TIME concern. The compiler cannot tell which .c a symbol
came from: `builtin_arity` in el-compiler/src/codegen.el maps NAME -> ARITY
INT only, the El name is emitted as the exact C symbol, and `ld` resolves it.
The SHIPPED compiler already links from ten translation units — check it:
nm lang/dist/platform/elc | grep -E 'T _(engram_think|vindex_insert)'
So a builtin defined in a sibling .c is EXACTLY as linkable as one defined in
el_runtime.c. Pick the file that owns the concern:
engram store ops ......... lang/runtime/engram_store.c
ANN / vector index ....... lang/runtime/engram_vindex.c
geometry, priming ........ lang/runtime/engram_geometry.c
reasoning operators ...... lang/runtime/engram_reason.c
grounding, consistency ... lang/runtime/engram_verify.c
think, stance ............ lang/runtime/engram_cognition.c
No existing file owns it? Create one, add ONE line to lang/runtime/SOURCES,
and every build path picks it up. Every runtime file EXCEPT el_runtime.c is
deliberately uncapped.
Belongs to a downstream program, not the runtime? Declare
`c_source "path/to/file.c"` in that program's manifest.el — elb already links
it (parse_manifest_c_sources, lang/elb.el:82).
See lang/AGENTS.md "Where a new C builtin goes".
MSG
}
# --- 1. Line-count ratchet ---------------------------------------------------
LINES="$(wc -l < "$TARGET" | tr -d ' ')"
if [ "$LINES" -gt "$MAX_LINES" ]; then
echo "FAIL: $TARGET grew past its budget." >&2
echo " now: $LINES lines" >&2
echo " budget: $MAX_LINES lines (lang/runtime/BUDGET: max_lines)" >&2
echo " over by: $((LINES - MAX_LINES))" >&2
echo "" >&2
echo "This file is a 2026-05-03 build shim that was scheduled for deletion and" >&2
echo "never retired. It does not get to grow. Do NOT raise the budget." >&2
where_it_goes
FAIL=1
fi
# --- 2. Engram-concern ratchet ----------------------------------------------
# ~47.5% of el_runtime.c is engram code, and engram already owns six sibling
# files. This count is the Stage 3 scoreboard: it may only go down.
ENGRAM_FNS="$(grep -cE '^(static +)?[A-Za-z_][A-Za-z0-9_ *]*\b(engram|eg|cog)_[a-z0-9_]+\(' "$TARGET" || true)"
if [ "$ENGRAM_FNS" -gt "$MAX_ENGRAM" ]; then
echo "FAIL: new engram/eg_/cog_ function(s) added to $TARGET." >&2
echo " now: $ENGRAM_FNS definitions" >&2
echo " budget: $MAX_ENGRAM (lang/runtime/BUDGET: max_engram_fns)" >&2
echo "" >&2
echo "Engram code belongs in the six engram_*.c files that already exist." >&2
where_it_goes
FAIL=1
fi
# --- 3. Ratchet-down nudge (advisory, never fails) ---------------------------
if [ "$LINES" -lt "$MAX_LINES" ]; then
echo "NOTE: $TARGET is $((MAX_LINES - LINES)) lines under budget — lower" >&2
echo " 'max_lines' to $LINES in $BUDGET_FILE in this same commit, so the" >&2
echo " ground you gained cannot be quietly given back." >&2
fi
if [ "$ENGRAM_FNS" -lt "$MAX_ENGRAM" ]; then
echo "NOTE: $((MAX_ENGRAM - ENGRAM_FNS)) engram fn(s) moved out — lower" >&2
echo " 'max_engram_fns' to $ENGRAM_FNS in $BUDGET_FILE in this same commit." >&2
fi
# --- 4. Every runtime .c is accounted for ------------------------------------
# A new .c that is in neither SOURCES nor the optional list will not be
# compiled by any build path — it would be silently dead. Catch that here.
OPTIONAL_RE='^(el_android|el_gtk4|el_lvgl|el_sdl2|el_win32|el_runtime_win32|eg_cosine_batch_strategy_ggml|vindex_bench)\.c$'
mapfile -t IN_SOURCES < <(scripts/el-runtime-sources.sh)
for path in "$RUNTIME_DIR"/*.c; do
base="$(basename "$path")"
if printf '%s\n' "${IN_SOURCES[@]}" | grep -qxF "$base"; then continue; fi
if [[ "$base" =~ $OPTIONAL_RE ]]; then continue; fi
echo "FAIL: $path is in neither lang/runtime/SOURCES nor the platform-optional" >&2
echo " list in this guard. It will not be compiled by any build path." >&2
echo " Add it to SOURCES (one line), or add it to OPTIONAL_RE here if it" >&2
echo " is a platform/strategy variant that is linked in deliberately." >&2
FAIL=1
done
# --- 5. install.sh must not drift from SOURCES -------------------------------
# install.sh runs on machines with no repo checkout, so it cannot call
# el-runtime-sources.sh and has to hardcode the list. That copy is exactly the
# kind of duplicate that silently drifted before — so it is checked, not trusted.
INSTALL_SH="lang/install.sh"
if [ -f "$INSTALL_SH" ]; then
EXPECTED="$(scripts/el-runtime-sources.sh | sort)"
ACTUAL="$(sed -n '/^RUNTIME_SOURCES=(/,/^)/p' "$INSTALL_SH" \
| grep -oE '[a-z_0-9]+\.c' | sort)"
if [ "$EXPECTED" != "$ACTUAL" ]; then
echo "FAIL: $INSTALL_SH RUNTIME_SOURCES has drifted from $SOURCES_FILE." >&2
echo " Only in SOURCES: $(comm -23 <(echo "$EXPECTED") <(echo "$ACTUAL") | tr '\n' ' ')" >&2
echo " Only in install.sh: $(comm -13 <(echo "$EXPECTED") <(echo "$ACTUAL") | tr '\n' ' ')" >&2
echo " An SDK that ships the wrong set produces a lib/ that cannot link." >&2
FAIL=1
fi
fi
if [ "$FAIL" -ne 0 ]; then
exit 1
fi
echo "OK: el_runtime.c within budget ($LINES/$MAX_LINES lines, $ENGRAM_FNS/$MAX_ENGRAM engram fns);"
echo " runtime sources accounted for; install.sh in step with SOURCES."
+9 -9
View File
@@ -81,14 +81,14 @@ fi
echo "OK: single canonical runtime source — $CANONICAL (no un-allowlisted forks)."
# ---------------------------------------------------------------------------
# CI wire-in:
# foundation/el .gitea/workflows/ci-dev.yaml, ci-stage.yaml, sdk-release.yaml
# Add an early step (before the build/publish steps). It must run from the
# REPO ROOT, so override the job's `defaults.run.working-directory: lang`:
# CI wire-in — DONE (2026-08-16). This block used to describe the wire-in as a
# TODO, and it had never been done: the guard existed but ran nowhere, so it
# caught nothing for as long as it has been in the tree. It is now an early step
# in ci-dev.yaml, ci-stage.yaml and sdk-release.yaml (each with
# `working-directory: ${{ github.workspace }}`, since the jobs default to lang/),
# and it runs in .githooks/pre-commit.
#
# - name: Guard - single canonical runtime source
# working-directory: ${{ github.workspace }}
# run: bash scripts/check-single-runtime.sh
#
# Also add to .githooks/pre-commit so drift is caught before it is committed.
# Its sibling scripts/check-runtime-growth.sh is wired in at the same points and
# guards the other half of the problem: this script stops el_runtime.c being
# COPIED, that one stops it GROWING.
# ---------------------------------------------------------------------------
+73
View File
@@ -0,0 +1,73 @@
#!/usr/bin/env bash
# el-runtime-sources.sh — print the canonical El runtime link set.
#
# Reads lang/runtime/SOURCES (the single source of truth) and prints one path
# per line, optionally prefixed with a directory. Use it anywhere a link line
# would otherwise spell the runtime .c files out longhand:
#
# cc -std=c11 -O2 -I lang/runtime -o app app.c \
# $(scripts/el-runtime-sources.sh lang/runtime) \
# -lcurl -lssl -lcrypto -lpthread -lm
#
# Options:
# --headers print the shipped headers instead of the .c sources
# --check verify every listed file exists; exit non-zero if any is missing
#
# WHY: linking el_runtime.c alone has been broken since el_runtime.c started
# calling into the engram siblings. The list was duplicated across ~8 build
# paths and drifted. It lives in exactly one place now — see lang/runtime/SOURCES.
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
SOURCES="${ROOT}/lang/runtime/SOURCES"
if [ ! -f "$SOURCES" ]; then
echo "FATAL: canonical runtime source list missing: $SOURCES" >&2
exit 1
fi
MODE="sources"
PREFIX=""
CHECK=0
for arg in "$@"; do
case "$arg" in
--headers) MODE="headers" ;;
--check) CHECK=1 ;;
-*) echo "el-runtime-sources.sh: unknown option: $arg" >&2; exit 2 ;;
*) PREFIX="${arg%/}/" ;;
esac
done
# Strip comments and blank lines. Order is preserved — it is link order.
mapfile -t FILES < <(sed -e 's/#.*//' -e 's/[[:space:]]*$//' "$SOURCES" | grep -v '^$')
if [ "${#FILES[@]}" -eq 0 ]; then
echo "FATAL: $SOURCES lists no sources" >&2
exit 1
fi
if [ "$MODE" = "headers" ]; then
# Every .c's matching .h, plus the headers that carry no .c of their own.
HDRS=()
for f in "${FILES[@]}"; do
h="${f%.c}.h"
[ -f "${ROOT}/lang/runtime/${h}" ] && HDRS+=("$h")
done
# Interface-only headers: no matching .c, but required to compile against.
for h in eg_cosine_batch_strategy.h el_native_target.h el_platform_win.h; do
[ -f "${ROOT}/lang/runtime/${h}" ] && HDRS+=("$h")
done
FILES=("${HDRS[@]}")
fi
RC=0
for f in "${FILES[@]}"; do
if [ "$CHECK" -eq 1 ] && [ ! -f "${ROOT}/lang/runtime/${f}" ]; then
echo "MISSING: lang/runtime/${f} (listed in lang/runtime/SOURCES)" >&2
RC=1
fi
printf '%s%s\n' "$PREFIX" "$f"
done
exit $RC