* empty
* docs: validate "See Also" references, drop dead ones, document valid_ffi
Reviewed the "See Also" section of every doc and dropped man-page
cross-references whose target page does not exist (verified against the
driver source, not just the docs tree):
- errorp, each, opcprof, dump_socket_status, extract, shadowp,
destruct_env_of, move, inventory_visible, inventory_accessible
These name efuns/applies that no longer exist in FluffOS. keys/values now
point at the `for` construct in place of the defunct `each` efun.
valid_ffi was the one "referenced but undocumented" case: it is a real
master apply (APPLY_VALID_FFI) gating every ffi_load/symbol/prepare/
callback, so it gets a proper apply page rather than having its references
removed. Sidebar regenerated to include it.
The 13 modern markdown-link "See Also" sections were already clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: fully-expandable generated sidebar, replacing index.md link pages
Rework docs navigation so the sidebar expands to every page of every
reference tree, instead of terminating at generated index.md link lists:
- New docs/gen_sidebar.py (replaces gen_index.py + update_index.sh):
walks efun/, apply/, stdlib/, concepts/, driver/, cli/ and zh-CN/ and
emits sidebars.generated.json — a full Docusaurus category tree per
directory. Category landing pages are now `generated-index` card pages
(title/description/slug), so all generated index.md files are deleted.
--check mode verifies freshness; new .github/workflows/docs-sidebar.yml
runs it in CI.
- New docs/sidebar_meta.json holds curated presentation: category labels,
one-line descriptions (shown on the landing cards), explicit ordering
(driver/cli/concepts read top-down from user-facing to internals) and
per-page label overrides.
- sidebars.ts becomes a hand-authored skeleton (Getting Started, lpc/,
Historical) that splices in the generated trees.
Content reorganization (from a docs-wide review):
- Move misplaced efun pages out of efun/general: terminal/protocol efuns
(act_mxp, send_zmp, request_term_*) to interactive/, debugging efuns
(check_memory, dump_*, clear_debug_level, destructed_objects) to
internals/, shallow_inherit_list to system/.
- Delete stub duplicates superseded by complete pages elsewhere:
general/parse_{add_synonym,dump,my_rules,remove}, contrib/{shuffle,
element_of}.
Modernize key pages with MDX:
- index.mdx: landing page with a card grid linking each doc section.
- build.mdx: per-platform <Tabs> (Ubuntu/macOS/Windows/Alpine+Docker),
admonitions, VitePress [[toc]] leftover removed, stale per-platform CI
workflow links updated to the unified ci.yml.
- ffi-plan.md: GitHub-style [!CAUTION] alert converted to an admonition.
`npm run build` passes clean (onBrokenLinks: throw, no warnings).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174GM2azvAHBmvyESwxm5om
* docs: serve the Chinese corpus through Docusaurus i18n
Move the zh-CN/ directory out of the default docs tree and into a proper
Docusaurus locale (i18n/zh-CN/docusaurus-plugin-content-docs/current/):
- The flat zh-CN/efun/ directory (333 pages) is re-homed to mirror the
categorized English layout (name-matched 1:1; `hash` maps to strings/
per its own frontmatter). apply/ pages map 1:1; the stray English-text
zh-CN/apply/master/view_errors.md documents a MudOS-era apply that no
longer exists in the driver and is dropped; stdlib/db/database_zh.md
becomes the i18n translation of stdlib/db/database.md; the Chinese
build guide becomes the translation of build.mdx.
- Untranslated pages automatically fall back to English content under
/zh-CN/, so the whole site is navigable in either locale from the new
navbar locale dropdown.
- Both locales share one sidebar. Generated sidebar items now carry
stable `key` fields (the directory/doc path) so translation keys are
unique (both efun/ and stdlib/ have an "Arrays" category, crypto and
strings both document `hash`). Category labels, generated-index
titles/descriptions, navbar and footer are translated in
i18n/zh-CN/...; theme UI strings come from Docusaurus' bundled
zh-Hans translations. Translated landing page at /zh-CN/.
- The "中文文档" sidebar section, the zh-CN tree in gen_sidebar.py /
sidebar_meta.json, and its slice of sidebars.generated.json are gone.
- Relative .md-file links on pages that render in both locales break
the localized build (the file->permalink map points at the localized
copy), so concepts/, the two socket_*_option pages and the config.md
generator now emit extension-less route links instead.
- zh interactive.md/objects.md get explicit slugs like their English
counterparts (a doc named after its parent directory is otherwise a
Docusaurus category-index doc, colliding with the generated-index
route).
`npm run build` builds both locales clean (onBrokenLinks: throw).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174GM2azvAHBmvyESwxm5om
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Add recompile_object() efun: in-place program update, state preserved
Recompiles a master copy's program from its source file and swaps the
fresh program into the LIVE master copy and every clone sharing it -
the "hot update" alternative to destruct+load_object: nothing is
destructed, so object identity (pointers held elsewhere, name,
inventory, shadows, interactive state, call_outs, heart_beat) is
untouched, and each object's global variables carry over BY NAME
inside the driver (private ones included): the new program's __INIT
runs first, then every surviving name gets its old value back. The
recompile behaves like a normal load - unloaded parents resolve
through the retry dance and the compile-time master applies are
consulted. Returns the number of objects updated.
Made possible by moving an object's variable block OUT of the object_t
allocation into its own (TAG_OBJ_VARS, always >= 1 svalue, wired into
the debug-malloc walkers): every access already went through
ob->variables[i], so a program with a different variable count can now
be swapped onto a live object.
Safety: refused while any object sharing the program is executing
anywhere on the call stack (live frames hold bytecode positions and
variable indices of the old layout), for clones (pass the master
copy), the simul_efun object, pending replace_program(), and nested
calls. Function pointers whose behavior depends on the owner's program
layout (FP_LOCAL, FP_FUNCTIONAL) go stale instead of corrupting:
objects carry a prog_generation stamp, funptrs snapshot it at
creation/bind, and call_function_pointer() errors cleanly on mismatch.
Fixing a latent asymmetry this exposed: make_lfun_funp incremented
func_ref on the creation-time program but dealloc_funp decremented the
owner's CURRENT program. FP_LOCAL pointers now store their program and
account against it symmetrically (checkmemory and %O formatting
updated to match) - caught by the debug-build memory checker in the
testsuite.
The hot-reload daemon's default (state-keeping) path now reloads
through recompile_object() - changed ancestors first, then the watched
program - so clones ride along automatically; a cooperative
hot_reload_state()/hot_reload_restore() pair takes the destruct+load
path with exactly the state it chooses, and watch(prog, 0) opts out
entirely. The daemon test demonstrates finding all live instances with
children()/clonep() and both clone behaviors (updated in place vs.
stragglers on the old program); single/tests/efuns/recompile_object.lpc
pins the efun semantics (master+clones count, per-object state incl.
private, initializers for new variables, removed variables, stale
funptrs, executing/clone/missing-source guards, call_out survival).
Docs: efun reference page, hot-reload guide step 5 rewritten around
the efun with the value-transfer technique kept as the manual
alternative, caveats updated (clone behavior per path, stale funptrs).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: support master/simul_efun targets; review fixes
The master object and the simul_efun object can now be recompiled
live. Both subsystems dispatch through cached name->runtime-index
tables (master_applies / simuls) whose entries point into the old
program's function table, so recompile_object() rebuilds them against
the new program immediately after the swap and BEFORE the new
program's __INIT runs (an error inside it would already route through
those tables). Simul_efun indices are preserved by NAME across the
rebuild - that table is deliberately unsorted for exactly this reason
- so simul calls compiled into every other program keep working, and
a simul removed by the new source fails with the usual "no longer a
simul_efun" runtime error. set_master()/set_simul_efun() only
ref/assign when the object actually changes, keeping the classic
destruct-driven replacement path intact. %O of a function pointer to
a since-removed simul now prints a placeholder instead of derefing
the null table entry.
Testsuite: the efun test recompiles the live simul_efun object
mid-run (the very next ASSERT dispatches through the rebuilt table),
pins the currently-executing guard on the master (master::flag() sits
on the call stack for the whole run), and re-runs the master recompile
from a post-run call_out where the master is idle - state carry-over
and apply dispatch are enforced by exiting nonzero.
Also from this self-review round (multi-agent):
* f_recompile_object crashed when the target destructed itself from
its new program's __INIT: destruct sweeps the VM stack, so the efun
glue's stack slot held a plain 0 by the time it tried to
free_object() it. Reproduced by a review agent's probe; the glue
now uses free_svalue(), and the scenario is pinned in the efun test
(destructed targets drop out of the updated count).
* hot_reload daemon: ancestors() now returns the inherit closure
DEEPEST-first - recompiling a middle parent bakes in whatever
grandparent program is live at that moment, so a >=3-level chain
with two changed ancestors permanently embedded the stale
grandparent (reproduced by a review agent; pinned by a new
kid/mid/grand scenario).
* hot_reload daemon: dep records were map_delete'd before the
recompile and rebuilt by the applies during it - but a throw BEFORE
compiling (currently-executing guard, unreadable file) left the
object loaded with no records, blinding closure_changed() to
include-file edits forever. Records are now restored when the
recompile throws (pinned by a new watched-object-drives-the-pass
scenario).
* docs: inheritance wording ("copies code" -> the child links against
the exact parent program it was compiled with), the
currently-executing guard also covers inheritors running inherited
code, and the cooperative-pair opt-out triggers on
hot_reload_state() alone.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: void mid-update replace_program; cover virtuals
Two additions from the C++ review round:
* A replace_program() registered DURING the update slipped past the
pre-flight check: an earlier target's __INIT can call into a
not-yet-swapped clone, whose OLD code registers a pending entry -
computed against the very program the update is replacing. The
backend sweep then ran that entry's variable-offset shuffle against
the fresh program's differently-sized variable block (negative
num_fewer, heap corruption; reproduced under ASan by a review
agent's probe). recompile_object() now voids any pending entry for
each target at its swap point - an entry registered AFTER the swap
is computed against the new program and survives. Pinned in the
efun test; the rest of the suite run doubles as the sweep detector.
* Virtual objects (materialized through master::compile_object) are
covered and pinned: the virtual object carries the BACKING file's
program, so the recompile targets that source and swaps it in with
the virtual name, identity, flag and state untouched. The testsuite
master gains a /data/hu/virt* fixture mapping; docs note the
behavior and that the hot-reload daemon keys its records by
compiled program name (watch virtuals via their backing file).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* docs: capture hot-reload/recompile_object knowledge in README and AGENTS
README: the hot-reload language bullet now describes what actually
ships (recompile_object with state carried by name, clones included),
and Features gains a Hot Reload section linking the guide.
AGENTS.md, for future agents working on this machinery: the object
variable block is a separate allocation (TAG_OBJ_VARS) and what that
enables; the new-DMALLOC-tag checklist (checkmemory walkers); the
destruct-sweeps-the-VM-stack rule for efun glue; testsuite harness
facts (fixtures outside tests/, unconditional teardown, master::flag
on the stack all run + the post-run call_out pattern, full -ftest
paths, suite side-effect files); the compile-time master applies; and
the recompile_object invariants (executing-frame guard, dispatch-table
rebuild before __INIT, voiding mid-update replace_program entries,
funptr generation staleness, FP_LOCAL func_ref symmetry).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: pin shadow/catch_tell/add_action/heart_beat survival
New test recompile_object2.lpc verifies the object-attached runtime
state that dispatches by name keeps working across the swap:
catch_tell routes into the new program while accumulated state stays;
a shadow chain survives updating the SHADOWED object (still
intercepted, new code underneath) and updating the SHADOW itself while
attached; add_action sentences registered by the old code still fire
their verb into the new program; the heart_beat registration persists.
Also two doc wording fixes from the docs review: the executing-guard
bullet now covers both halves of the guard (frames executing the
program's code AND frames belonging to an object of the program
running inherited code), and the guide's mode summary matches the
daemon (hot_reload_state alone selects the cooperative path).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: fix simul_efun/__INIT edge cases; cover callback surface
Four defects from the C++ review round, each probe-verified under ASan:
* Recompiling the simul_efun object to a program that defines no simuls
FREEd the live dispatch table (simul_names/simuls) while other
compiled programs still carry F_SIMUL_EFUN opcodes and FP_SIMUL
funptrs with baked indices -> use-after-free on the next simul call.
Keep the tombstoned arrays instead (remove_simuls() already nulls
every func, which yields the clean "no longer a simul_efun" error and
preserves the name->index mapping for re-adds).
* The debug memory checker did not mark IHE_ORPHAN idents as permanent,
so any run that removed a simul via an update tripped a spurious
"orphan permanent identifier" leak and failed the testsuite gate.
Add IHE_ORPHAN to the mark mask (it is part of IHE_PERMANENT).
* The disassembler dereferenced simuls[].func unguarded in two places;
after a simul removal, dump_prog() on a program referencing it would
null-deref. Guard both, matching the sprintf %O fix.
* An error() thrown from a target's __INIT during the swap leaked this
loop's held references (the per-target snapshot ref, new_prog's
compile ref, the old variable block) and left the update half-applied.
Wrap call___INIT per target in save_context/try/restore: on error the
object is left committed to the new program with fresh initializers
(carried-over state dropped, like a create() that throws during load),
sibling targets still update, and nothing leaks.
Test coverage:
* recompile_object.lpc: an __INIT that errors -- blueprint and clone
both recompile, neither is immortalized, the object stays usable on
the new program, no ref/variable leak (the per-file memory checker is
the detector). (The simul zero-function / removal paths can't be
exercised against the shared /single/simul_efun mid-suite; verified
out-of-band with a throwaway ASan probe that reduces then restores the
file.)
* recompile_object2.lpc: call_outs armed before the swap fire after it --
a name-based call_out dispatches into the new program, a funptr
call_out is stale and is refused cleanly (its target never runs, no
crash), verified from a post-run call_out. Rounds out the by-name
callback survivors already covered (catch_tell, add_action, heart_beat,
shadows).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
---------
Co-authored-by: Claude <noreply@anthropic.com>
* docs: add local full-text search and a contributor README
Add @easyops-cn/docusaurus-search-local to the Docusaurus site so the
docs get an offline search bar (index built at build time, no external
service). English and zh-CN pages are both indexed, and matched terms
are highlighted on the target page.
Add docs/README.md describing the Docusaurus setup, local dev/build
commands, search behavior, directory layout, and gotchas; exclude it
from the published site alongside CLAUDE.md. Point the root README's
docs/ entry at it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
* docs: remove dead framework leftovers, fix index generation, complete the nav
Delete the VitePress (.vitepress/) and Jekyll (_layouts/, css/) leftovers,
the one-shot migration scripts (fix_md_header.py, fix_seealso.py), and the
stale keywords.json snapshot; prune the matching .gitignore entries and
docusaurus exclude patterns.
Rewrite gen_index.py for Docusaurus: it emitted dead .html links and
legacy 'layout: doc' frontmatter, choked on non-markdown entries, and
dropped nested categories — regenerating an index would have broken it.
It now emits the extension-less links the site actually uses, links
nested category indexes (restoring apply/* on the zh-CN index), and
refuses to run on the docs root. Fix update_index.sh's copy-paste titles
(zh-CN efun/build were titled 'APPLY'), stop it clobbering the
hand-written lpc/index.md, and cover cli/. Regenerated indexes pick up
the missing driver/ffi-plan entry. add_missing_efuns.py now takes the
keywords.json path as an argument instead of requiring a stale copy.
Move CNAME and the Google site-verification file into static/ so they
actually reach the published build output.
Complete the sidebar: link the CLI category to cli/index and add the
missing portbind/symbol/generate_keywords pages, and expose the
previously orphaned stdlib section under Reference.
Promote onBrokenLinks to 'throw' now the build is warning-free, and drop
the empty Demo section from the landing page.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
* docs: strip legacy 'layout: doc' frontmatter from all pages
Mechanical sweep removing the Jekyll-era 'layout: doc' line from every
doc page's frontmatter (Docusaurus ignores it), and the matching line
from the templates in docs/CLAUDE.md so new pages don't reintroduce it.
No content changes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
---------
Co-authored-by: Claude <noreply@anthropic.com>
Reviewed every efun doc against the .spec source of truth (the make_func
declarations) and the implementations.
New docs for 28 previously-undocumented efuns:
- package_ffi (18): new docs/efun/ffi/ category — ffi_load/unload/symbol/
prepare/call, alloc/free/sizeof/peek/address/read/write, struct_layout,
callback/callback_addr/callback_free, error/status.
- package_dwlib (10, under contrib/): add_a, vowel, replace,
replace_dollars/html/mxp/objects, roulette_wheel, query_multiple_short,
reference_allowed.
Return-type fixes where the doc contradicted the spec/impl (mostly stale
MudOS behavior): cache_stats/debugmalloc/dump_file_descriptors/
malloc_status/mud_status return string; disable_commands/flush_messages/
receive/set_heart_beat are void; get_char/input_to/link/set_eval_limit
return int; call_stack -> mixed *, function_profile -> mapping *. Also
corrected receive's and disable_commands' stale "returns ..." prose.
Expanded implode (function-fold form) and save_object (save-to-string
form), both of which the docs had omitted.
Removed 4 stale docs for efuns that no longer exist (no spec entry, no
f_ implementation, zero references anywhere): errorp, opcprof, swap,
dump_socket_status.
Regenerated the affected efun index pages. The Docusaurus build passes
with onBrokenLinks:throw, confirming no dangling links.
Note: the docs/zh-CN translated tree still mirrors the old English docs
(same stale entries, and it lacks the new efuns); left for a separate
translation pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Reorder sidebar: Driver > CLI > Reference (LPC Language, Apply, EFUN, Concepts)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Fix Docusaurus build: broken links, duplicate routes, and gh-pages CI
- Strip .html from all markdown link targets (51 files) for Docusaurus URL routing
- Add slug: frontmatter to 4 files whose names match their parent directory
(interactive.md, objects.md, README.md, build.md) to prevent Docusaurus's
category-index convention from creating duplicate routes
- Fix one missed .html link in zh-CN/build/index.md
- Move onBrokenMarkdownLinks to markdown.hooks (Docusaurus v4 deprecation)
- Update gh-pages.yml: rename to Docusaurus, use node 22, correct build path
(docs/build instead of docs/.vitepress/dist)
Build now completes with [SUCCESS] and zero warnings or broken links.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* Add documentation for missing parsing functions and update existing entries
* ran `update_index.sh` and evidently some index.md files needed updating that hadn't been in the past. they were lonely and i thought, well, why not come along for the ride. you are welcome to join the rest of us in the parade of documentation updates.
* Notify object that it is scheduled for destruction
* adding documentation
* adding try/catch to allow destruction to continue even with mudlib errors
* updating and adding new supporting efuns
* adding documentation
* tests written for on_destruct
* fixy fixy?
* another try?
* moving test objects to /single. maye this was causing the compile check issues?
---------
Co-authored-by: Yucong Sun <sunyucong@gmail.com>
