GizStack
View .mdOpen in ChatGPTOpen in Claude

Repository Structure and Package Boundaries

The Gizlang monorepo is organized into strictly layered packages defined in structure/packages and enforced on every check by bin/gizlang structure (Tools internals). Every .giz and .ghtml source file belongs to exactly one package by longest path prefix match.

Structural Enforcement Rules

bin/gizlang structure verifies eight invariants across the checkout without compiling whole programs:

RuleInvariant EnforcedConfiguration Source
reverseA package may import only packages listed in its depends clausestructure/packages
privateCross-package imports may target only modules matching the target package's public globs (or white-box mirrors)structure/packages
layerFiles in a package's layer list may never reach files in its never list through any transitive import chainstructure/packages
cyclePackage-level cycles, cross-package file cycles, and intra-package file cycles are forbiddenstructure/packages
conceptShared platform types and constructors may be declared or called only in their designated owner modulestructure/concepts
legacyRetired syntax and API forms listed in structure/legacy may never be introducedstructure/legacy
duplicateFunctions (3+ statements) and string literal tables (6+ items) may not be duplicated across or within packagesToken SHA-256 digest
data & unownedTest corpora under tests/ and bench/ must be pinned in tests/data.lock, and every path must match an structure/owners entrytests/data.lock, structure/owners

Packages and Public Interfaces

The table below is generated and verified by bin/gizlang structure --doc from structure/packages and structure/owners.

<!-- structure:packages -->

PackagePathsContentsOwnerMay importPublic modules
compilercompiler/The compiler's core: lexer, parser, checker, code generation, outline, graph and meaning hashes@gizai/compilernonecompiler/layout.giz, compiler/tokens.giz, compiler/libraries.giz
compiler-drivercompiler/driver/The compiler's driver on its core: entry, tool protocol, edit transactions, resident check, explain, inspection@gizai/compilercompilernone
runtimeruntime/, bin/, bootstrap/The runtime in C and in Gizlang (runtime/package.json): memory, tasks, system calls, the compiler driver; the Gizlang C library of static Linux programs@gizai/runtimesdknone
sdksdk/The standard library core (gizlang/*): language values, text, collections, system, tasks, time, JSON, crypto, compression, regex, locale, linear algebra, statistics@gizai/sdk; sdk/net/: @gizai/net; sdk/sql/: @gizai/datanonesdk/core/*.giz, sdk/graphics/*.giz, sdk/wayland/*.giz, sdk/main.giz
sdk-formatsdk/format/File formats of the standard library: CSV, HTML, Jinja templates, PDF, images, protobuf, journal, erasure codes, MP4, safetensors, GGUF@gizai/sdksdksdk/format/*.giz
hwhw/GizHW (gizhw), hardware: the machine (CPU, caches, memory nodes), devices and their readings, GPUs and GPU kernels, the GPUs' video codecs@gizai/hardwaresdk-format, sdkhw/*.giz
sdk-netsdk/net/Network protocols and services of the standard library: HTTP 1-3, TLS, gRPC, mesh, gateway, ACME, metrics, the model hub client, workers@gizai/netsdk-format, sdksdk/net/*.giz
sdk-mediasdk/media/, sdk/window/Devices and windows of the standard library: sound, cameras, media playback, and desktop windows on Wayland@gizai/sdksdk-net, sdk-format, sdksdk/media/*.giz, sdk/window/*.giz
sdk-sqlsdk/sql/The one SQL connection API of the standard library (gizlang/sql) and its drivers: PostgreSQL, SQLite, and ODBC on giz@gizai/datasdk-net, sdksdk/sql/*.giz
aiai/GizAI (gizai), compute and models: tensors, network operations, weight formats, decoding grammars, autograd, networks, classical ML, tokenizers, LLM, diffusion, video, ONNX@gizai/aimodel, fs, hw, sdk-net, sdk-format, sdkai/*.giz, ai/agent/research.giz, ai/agent/connections.giz, ai/agent/code.giz, ai/agent/coding.giz, ai/agent/mcp.giz, ai/agent/a2a.giz, ai/ml/*.giz, ai/written/*.giz, ai/tensor/core.giz, ai/render/gaussians.giz, ai/models/lam/expression.giz, ai/models/resplat/model.giz, ai/models/pi3/model.giz, ai/models/resplat/family.giz, ai/models/resplat/experiment.giz, ai/tensor/lazy.giz, ai/tensor/linalg.giz, ai/tensor/stats.giz, ai/llm/convert.giz, ai/llm/engine.giz, ai/llm/kvformat.giz, ai/llm/learn.giz, ai/llm/corpus.giz, ai/llm/score.giz, ai/llm/model.giz, ai/llm/state.giz, ai/llm/encoders.giz, ai/llm/sample.giz, ai/onnx/decode.giz, ai/onnx/encode.giz, ai/onnx/model.giz, ai/tasks/image.giz, ai/parts/tune.giz, ai/tasks/video.giz, ai/tasks/transcription.giz, ai/tasks/object.giz, ai/tasks/cutout.giz, ai/tasks/dialogue.giz, ai/tasks/speech.giz, ai/video/decode.giz, ai/video/frames.giz, ai/video/wav.giz
vmvm/The VM for JavaScript, TypeScript and Python: values, objects, GC, bytecode, interpreter, both realms@gizai/vmsdk-sql, sdk-net, sdkvm/main.giz, vm/wasm.giz, vm/wasmsimd.giz, vm/host.giz, vm/node/resolution.giz, vm/jsparse.giz, vm/ast.giz
vm-luavm/lua.gizLua 5.1 to embed (gizvm/lua): a parser and an interpreter on the SDK only, so GizDB's KV scripts do not link the VM@gizai/vmsdkvm/lua.giz
clitools/cli/The command line (gizlang) and its package commands@gizai/toolsrelease, sdk-net, sdk-format, sdk, compilertools/cli/ar.giz, tools/cli/bare.giz, tools/cli/repository.giz, tools/cli/files.giz, tools/cli/layout.giz, tools/cli/commands.giz, tools/cli/settings.giz, tools/cli/format.giz, tools/cli/slots.giz, tools/cli/compile.giz, tools/cli/sources.giz, tools/cli/buildstore.giz, tools/cli/toolchain.giz, tools/cli/unitlibs.giz, tools/cli/inputs.giz, tools/cli/python.giz, tools/cli/functions.giz, tools/cli/scriptinput.giz, tools/cli/nodelib.giz, tools/cli/build.giz, tools/cli/packages.giz, tools/cli/doc.giz, tools/cli/ci.giz, tools/cli/split.giz, tools/cli/ghtml.giz, tools/cli/bundle.giz, tools/cli/bench.giz, tools/cli/cloud.giz, tools/cli/init.giz, tools/cli/licenses.giz, tools/cli/machine.giz, tools/cli/frames.giz
releasetools/distribution/release.giz, tools/distribution/native.giz, tools/distribution/install.giz, tools/distribution/targets.giz, tools/distribution/license.giz, tools/distribution/channels/channels.giz, tools/distribution/access.giz, tools/distribution/packages.giz, tools/distribution/changes.gizRelease and package formats: identities, targets, licenses, channels, Mach-O, the archive, the signed envelope, the preview access token, the installed release and its parts, and the package registry's rules. The CLI reads them, distribution writes them, the site shows and serves them@gizai/releasesdk-net, sdk, compilertools/distribution/release.giz, tools/distribution/native.giz, tools/distribution/install.giz, tools/distribution/targets.giz, tools/distribution/license.giz, tools/distribution/channels/channels.giz, tools/distribution/access.giz, tools/distribution/packages.giz, tools/distribution/changes.giz
distributiontools/distribution/build.giz, tools/distribution/builder.giz, tools/distribution/launcher.giz, tools/distribution/publication.giz, tools/distribution/reference.giz, tools/distribution/installer.giz, tools/distribution/channels/packages.gizRelease builds, installers, publication@gizai/releaserelease, cli, sdk-net, sdktools/distribution/build.giz, tools/distribution/builder.giz, tools/distribution/publication.giz
ai-apptools/ai/app/The app of giz ai on a terminal: the models, a chat whose answer grows as it comes, and pictures, on the app shell (gizapps)@gizai/appsapps, browser, web, db, model, ai, hw, sdk-media, sdk-sql, sdk-net, sdk-format, sdktools/ai/app/main.giz
toolstools/Developer tools: language server, REPL, codec, patch queue, test harness, hooks@gizai/tools; tools/cli/: @gizai/tools; tools/ai/app/: @gizai/apps; tools/distribution/: @gizai/releaserelease, cli, ai-app, ai, vm, hw, sdk-media, sdk-sql, sdk-net, sdk-format, sdk, compiler, fstools/harness.giz, tools/conformance/wast.giz, tools/duckdb.giz, tools/odbc.giz, tools/fs/fixture.giz, tools/gizdb-node.giz, tools/browser/cdp.giz, tools/npm/resolve.giz, tools/npm/store.giz, tools/npm/cache.giz, tools/ai/registry.giz, tools/ai/train.giz
fsfs/GizFS (gizfs): the global storage: disk I/O, codecs, consensus, file and object access@gizai/storagesdk-net, sdk-format, sdkfs/disk.giz, fs/bucket.giz, fs/fs.giz, fs/codec.giz, fs/ordered.giz, fs/raft.giz, fs/cli.giz, fs/object.giz, fs/volume.giz, fs/node.giz, fs/s3.giz
modelmodel/GizModel (gizmodel): the application data layer on gizlang/sql: record shapes, typed queries, sources, policies, live feeds, search, and the SQL tree with its dialects@gizai/datafs, sdk-sql, sdk-net, sdk-format, sdkmodel/*.giz, model/core/*.giz, model/sql/*.giz, model/sql/types/*.giz, model/sql/catalog/*.giz
dbdb/GizDB (gizdb): the engine: storage, SQL execution, protocols, the embedded database and its application host@gizai/database; db/ml/: @gizai/aimodel, web, fs, vm-lua, sdk-sql, sdk-net, sdk-format, sdkdb/main.giz, db/app.giz, db/rank.giz, db/access.giz, db/workbench.giz, db/migrate.giz, db/core/vector.giz, db/server/server.giz, db/local.giz, db/pg/cluster.giz, db/sql/source.giz, db/kv/local.giz, db/kv/state.giz
db-mldb/ml/, db/pg/main.gizPostgresML in GizDB (CREATE EXTENSION pgml: training, embedding, generation in SQL) on gizai, and the gizdb program that links it@gizai/aidb, model, fs, ai, hw, sdk-sql, sdk-net, sdk-format, sdkdb/ml/pgml.giz, db/ml/embed.giz
webweb/GizWeb: the web framework (gizweb). No product code.@gizai/webmodel, sdk-sql, sdk-net, sdk-format, sdkweb/main.giz, web/pages.giz, web/protocol.giz, web/client/kernel.giz, web/client/page.giz, web/table.giz, web/jobs.giz, web/presence.giz, web/outbox.giz, web/files.giz, web/region.giz, web/chatui.giz, web/visual.giz, web/view.giz, web/auth/main.giz
browserbrowser/GizBrowser (gizbrowser): the browser engine. HTML, CSS, style, layout and paint to pixels, with no operating system call of its own@gizai/browservm, web, sdk-media, sdk-net, sdk-format, sdkbrowser/*.giz
appsapps/GizApps (gizapps): a GizWeb app run as a program (host), shown by a front end on a terminal's whole screen (tui) or in a window of its own. No product code.@gizai/appsbrowser, web, sdk-media, sdk-net, sdk-format, sdkapps/host.giz, apps/tui.giz, apps/window.giz
browser-appbrowser-app/GizBrowser, the desktop web browser: a window of tabs on the engine (gizapps/window), its own pages a GizWeb app@gizai/appsapps, browser, web, db, model, sdk-media, sdk-sql, sdk-net, sdk-format, sdknone
deskdesk/GizDesk (gizdesk): the open-source agent workspace, durable runs, actions, connections and standalone app@gizai/deskapps, web, db, model, fs, ai, hw, sdk-sql, sdk-net, sdk-format, sdkdesk/model.giz, desk/studio.giz, desk/actions.giz, desk/agent.giz, desk/execution.giz, desk/media.giz, desk/runs.giz, desk/triggers.giz, desk/site.giz, desk/ml.giz, desk/character.giz, desk/data.giz, desk/drive/*.giz, desk/drive/view.ghtml, desk/components/*.ghtml
teststests/The specification: golden cases, test files and scenario suites@gizai/maintainersevery packagetests/db/stored.giz, tests/web/pages/.routes, tests/web/i18n/pages/.routes
benchbench/Benchmarks against other languages and systems@gizai/maintainersevery packagenone
examplesexamples/Programs that must build and run@gizai/docsevery packagenone

<!-- /structure:packages -->

Dependency Direction

Packages form a strict directed acyclic graph (DAG) from the compiler and core SDK at the bottom to apps, desk, tests, bench, and examples at the top:

<!-- structure:direction -->

compiler -> (nothing)
compiler-driver -> compiler
runtime -> sdk
sdk -> (nothing)
sdk-format -> sdk
hw -> sdk-format, sdk
sdk-net -> sdk-format, sdk
sdk-media -> sdk-net, sdk-format, sdk
sdk-sql -> sdk-net, sdk
ai -> model, fs, hw, sdk-net, sdk-format, sdk
vm -> sdk-sql, sdk-net, sdk
vm-lua -> sdk
cli -> release, sdk-net, sdk-format, sdk, compiler
release -> sdk-net, sdk, compiler
distribution -> release, cli, sdk-net, sdk
ai-app -> apps, browser, web, db, model, ai, hw, sdk-media, sdk-sql, sdk-net, sdk-format, sdk
tools -> release, cli, ai-app, ai, vm, hw, sdk-media, sdk-sql, sdk-net, sdk-format, sdk, compiler, fs
fs -> sdk-net, sdk-format, sdk
model -> fs, sdk-sql, sdk-net, sdk-format, sdk
db -> model, web, fs, vm-lua, sdk-sql, sdk-net, sdk-format, sdk
db-ml -> db, model, fs, ai, hw, sdk-sql, sdk-net, sdk-format, sdk
web -> model, sdk-sql, sdk-net, sdk-format, sdk
browser -> vm, web, sdk-media, sdk-net, sdk-format, sdk
apps -> browser, web, sdk-media, sdk-net, sdk-format, sdk
browser-app -> apps, browser, web, db, model, sdk-media, sdk-sql, sdk-net, sdk-format, sdk
desk -> apps, web, db, model, fs, ai, hw, sdk-sql, sdk-net, sdk-format, sdk
tests -> every package (public modules; a mirrored package in full)
bench -> every package (public modules; a mirrored package in full)
examples -> every package (public modules; a mirrored package in full)

<!-- /structure:direction -->

Code Ownership

Each path prefix in the repository is stewarded by the team listed in structure/owners:

<!-- structure:owners -->

PathOwner
.@gizai/maintainers
compiler/@gizai/compiler
runtime/@gizai/runtime
bin/@gizai/runtime
bootstrap/@gizai/compiler
sdk/@gizai/sdk
sdk/net/@gizai/net
sdk/sql/@gizai/data
hw/@gizai/hardware
ai/@gizai/ai
vm/@gizai/vm
tools/@gizai/tools
tools/cli/@gizai/tools
tools/ai/app/@gizai/apps
tools/distribution/@gizai/release
fs/@gizai/storage
model/@gizai/data
db/@gizai/database
db/ml/@gizai/ai
web/@gizai/web
browser/@gizai/browser
apps/@gizai/apps
browser-app/@gizai/apps
desk/@gizai/desk
docs/@gizai/docs
structure/@gizai/maintainers
tests/@gizai/maintainers
bench/@gizai/maintainers
examples/@gizai/docs

<!-- /structure:owners -->