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:
| Rule | Invariant Enforced | Configuration Source |
|---|---|---|
reverse | A package may import only packages listed in its depends clause | structure/packages |
private | Cross-package imports may target only modules matching the target package's public globs (or white-box mirrors) | structure/packages |
layer | Files in a package's layer list may never reach files in its never list through any transitive import chain | structure/packages |
cycle | Package-level cycles, cross-package file cycles, and intra-package file cycles are forbidden | structure/packages |
concept | Shared platform types and constructors may be declared or called only in their designated owner module | structure/concepts |
legacy | Retired syntax and API forms listed in structure/legacy may never be introduced | structure/legacy |
duplicate | Functions (3+ statements) and string literal tables (6+ items) may not be duplicated across or within packages | Token SHA-256 digest |
data & unowned | Test corpora under tests/ and bench/ must be pinned in tests/data.lock, and every path must match an structure/owners entry | tests/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 -->
| Package | Paths | Contents | Owner | May import | Public modules |
|---|---|---|---|---|---|
compiler | compiler/ | The compiler's core: lexer, parser, checker, code generation, outline, graph and meaning hashes | @gizai/compiler | none | compiler/layout.giz, compiler/tokens.giz, compiler/libraries.giz |
compiler-driver | compiler/driver/ | The compiler's driver on its core: entry, tool protocol, edit transactions, resident check, explain, inspection | @gizai/compiler | compiler | none |
runtime | runtime/, 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/runtime | sdk | none |
sdk | sdk/ | 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/data | none | sdk/core/*.giz, sdk/graphics/*.giz, sdk/wayland/*.giz, sdk/main.giz |
sdk-format | sdk/format/ | File formats of the standard library: CSV, HTML, Jinja templates, PDF, images, protobuf, journal, erasure codes, MP4, safetensors, GGUF | @gizai/sdk | sdk | sdk/format/*.giz |
hw | hw/ | GizHW (gizhw), hardware: the machine (CPU, caches, memory nodes), devices and their readings, GPUs and GPU kernels, the GPUs' video codecs | @gizai/hardware | sdk-format, sdk | hw/*.giz |
sdk-net | sdk/net/ | Network protocols and services of the standard library: HTTP 1-3, TLS, gRPC, mesh, gateway, ACME, metrics, the model hub client, workers | @gizai/net | sdk-format, sdk | sdk/net/*.giz |
sdk-media | sdk/media/, sdk/window/ | Devices and windows of the standard library: sound, cameras, media playback, and desktop windows on Wayland | @gizai/sdk | sdk-net, sdk-format, sdk | sdk/media/*.giz, sdk/window/*.giz |
sdk-sql | sdk/sql/ | The one SQL connection API of the standard library (gizlang/sql) and its drivers: PostgreSQL, SQLite, and ODBC on giz | @gizai/data | sdk-net, sdk | sdk/sql/*.giz |
ai | ai/ | GizAI (gizai), compute and models: tensors, network operations, weight formats, decoding grammars, autograd, networks, classical ML, tokenizers, LLM, diffusion, video, ONNX | @gizai/ai | model, fs, hw, sdk-net, sdk-format, sdk | ai/*.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 |
vm | vm/ | The VM for JavaScript, TypeScript and Python: values, objects, GC, bytecode, interpreter, both realms | @gizai/vm | sdk-sql, sdk-net, sdk | vm/main.giz, vm/wasm.giz, vm/wasmsimd.giz, vm/host.giz, vm/node/resolution.giz, vm/jsparse.giz, vm/ast.giz |
vm-lua | vm/lua.giz | Lua 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/vm | sdk | vm/lua.giz |
cli | tools/cli/ | The command line (gizlang) and its package commands | @gizai/tools | release, sdk-net, sdk-format, sdk, compiler | tools/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 |
release | tools/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 | Release 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/release | sdk-net, sdk, compiler | tools/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 |
distribution | tools/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.giz | Release builds, installers, publication | @gizai/release | release, cli, sdk-net, sdk | tools/distribution/build.giz, tools/distribution/builder.giz, tools/distribution/publication.giz |
ai-app | tools/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/apps | apps, browser, web, db, model, ai, hw, sdk-media, sdk-sql, sdk-net, sdk-format, sdk | tools/ai/app/main.giz |
tools | tools/ | 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/release | release, cli, ai-app, ai, vm, hw, sdk-media, sdk-sql, sdk-net, sdk-format, sdk, compiler, fs | tools/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 |
fs | fs/ | GizFS (gizfs): the global storage: disk I/O, codecs, consensus, file and object access | @gizai/storage | sdk-net, sdk-format, sdk | fs/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 |
model | model/ | 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/data | fs, sdk-sql, sdk-net, sdk-format, sdk | model/*.giz, model/core/*.giz, model/sql/*.giz, model/sql/types/*.giz, model/sql/catalog/*.giz |
db | db/ | GizDB (gizdb): the engine: storage, SQL execution, protocols, the embedded database and its application host | @gizai/database; db/ml/: @gizai/ai | model, web, fs, vm-lua, sdk-sql, sdk-net, sdk-format, sdk | db/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-ml | db/ml/, db/pg/main.giz | PostgresML in GizDB (CREATE EXTENSION pgml: training, embedding, generation in SQL) on gizai, and the gizdb program that links it | @gizai/ai | db, model, fs, ai, hw, sdk-sql, sdk-net, sdk-format, sdk | db/ml/pgml.giz, db/ml/embed.giz |
web | web/ | GizWeb: the web framework (gizweb). No product code. | @gizai/web | model, sdk-sql, sdk-net, sdk-format, sdk | web/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 |
browser | browser/ | GizBrowser (gizbrowser): the browser engine. HTML, CSS, style, layout and paint to pixels, with no operating system call of its own | @gizai/browser | vm, web, sdk-media, sdk-net, sdk-format, sdk | browser/*.giz |
apps | apps/ | 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/apps | browser, web, sdk-media, sdk-net, sdk-format, sdk | apps/host.giz, apps/tui.giz, apps/window.giz |
browser-app | browser-app/ | GizBrowser, the desktop web browser: a window of tabs on the engine (gizapps/window), its own pages a GizWeb app | @gizai/apps | apps, browser, web, db, model, sdk-media, sdk-sql, sdk-net, sdk-format, sdk | none |
desk | desk/ | GizDesk (gizdesk): the open-source agent workspace, durable runs, actions, connections and standalone app | @gizai/desk | apps, web, db, model, fs, ai, hw, sdk-sql, sdk-net, sdk-format, sdk | desk/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 |
tests | tests/ | The specification: golden cases, test files and scenario suites | @gizai/maintainers | every package | tests/db/stored.giz, tests/web/pages/.routes, tests/web/i18n/pages/.routes |
bench | bench/ | Benchmarks against other languages and systems | @gizai/maintainers | every package | none |
examples | examples/ | Programs that must build and run | @gizai/docs | every package | none |
<!-- /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 -->
| Path | Owner |
|---|---|
. | @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 -->