pietto 0.1.1__tar.gz

pietto-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mianli Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pietto-0.1.1/LICENSES/ANTLR-4.13.2-Python3-template-header.txt

@@ -0,0 +1,30 @@
+/*
+ * [The "BSD license"]
+ *  Copyright (c) 2012-2016 Terence Parr
+ *  Copyright (c) 2012-2016 Sam Harwell
+ *  Copyright (c) 2014 Eric Vergnaud
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions
+ *  are met:
+ *
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. The name of the author may not be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */

pietto-0.1.1/LICENSES/ANTLR-4.13.2.txt

@@ -0,0 +1,28 @@
+Copyright (c) 2012-2022 The ANTLR Project. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither name of copyright holders nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pietto-0.1.1/LICENSES/PostgreSQL-18.6.txt

@@ -0,0 +1,23 @@
+PostgreSQL Database Management System
+(also known as Postgres, formerly known as Postgres95)
+
+Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
+
+Portions Copyright (c) 1994, The Regents of the University of California
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement
+is hereby granted, provided that the above copyright notice and this
+paragraph and the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
+DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
+DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
+ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
+PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

pietto-0.1.1/LICENSES/SOURCES.md

@@ -0,0 +1,33 @@
+# Sources of the license texts
+
+Each license text in this directory is a byte-for-byte copy of the upstream
+file, or of the line range stated for it, at the commit, archive snapshot or
+tracked artifact listed below, retrieved on 2026-10-10 (UTC).
+
+Three upstream details:
+
+- The ANTLR 3.5.3 tag has no license file at the repository root or for the
+  Java runtime (`runtime/Java`, `org.antlr:antlr-runtime`) that the ANTLR jar
+  bundles. The closest text at that tag is `tool/LICENSE.txt`, copied here. The
+  runtime's own source headers read "Copyright (c) 2005-2009 Terence Parr"
+  (one file: 2012 Terence Parr, 2012 Sam Harwell).
+- The TreeLayout 1.0.3 tag ships a BSD license text, while its POM names
+  BSD-3-Clause with a URL to the abego Public Licence 1.0 page. Both texts are
+  kept.
+- Pietto's generated parser follows ANTLR's Python3 code-generation template.
+  That template's own BSD header differs from the ANTLR 4.13.2 `LICENSE.txt`, so
+  it is copied separately from the tracked ANTLR jar.
+
+| File | Upstream file | Pin | SHA-256 |
+| --- | --- | --- | --- |
+| `ANTLR-4.13.2.txt` | `https://github.com/antlr/antlr4/blob/cc82115a4e7f53d71d9d905caa2c2dfa4da58899/LICENSE.txt` (tag `4.13.2`) | commit `cc82115a4e7f53d71d9d905caa2c2dfa4da58899` | `3db1fb3ee79a4b4f9918fc4d0f6133bf18a3cf787f126cd22f8aa9b862281c0c` |
+| `ANTLR-4.13.2-Python3-template-header.txt` | Lines 1-30 of `org/antlr/v4/tool/templates/codegen/Python3/Python3.stg` inside `tools/antlr-4.13.2-complete.jar` (entry SHA-256 `87df5899ff72d31e9371cbda58c37e7f17a27469b85753d228243b44034dd576`) | jar SHA-256 `eae2dfa119a64327444672aff63e9ec35a20180dc5b8090b7a6ab85125df4d76` | `3bad51e28a4ecebcb8b9afdddf3bf38ef8279bc9349fa0102850ee0453a30b65` |
+| `ANTLR-3.5.3.txt` | `https://github.com/antlr/antlr3/blob/0519032bb167b37f206968d9037753ad655a2623/tool/LICENSE.txt` (tag `3.5.3`) | commit `0519032bb167b37f206968d9037753ad655a2623` | `95fc87cbe29814a32fc97f6f8eb7ae55e4816d4b75143635c4db736e7e374fa2` |
+| `StringTemplate-4.3.4.txt` | `https://github.com/antlr/stringtemplate4/blob/a2c4ef074e7c5018c7eb46372ed07f756c140404/LICENSE.txt` (tag `ST4-4.3.4`) | commit `a2c4ef074e7c5018c7eb46372ed07f756c140404` | `022bdae9c4f408d375f8c3c16b7695c22a2152c56535af180059e3ab92adffb0` |
+| `TreeLayout-1.0.3.txt` | `https://github.com/abego/treelayout/blob/fb5b5326d9fe642b9ca0631c3da739bf775f6374/org.abego.treelayout/src/LICENSE.TXT` (tag `v1.0.3`) | commit `fb5b5326d9fe642b9ca0631c3da739bf775f6374` | `b6fcaaa79c777ccd16e7493a0451eeaca22d7166782d1b962b49af410ed09e4f` |
+| `TreeLayout-1.0.3-abego-apl-v10.html` | `https://web.archive.org/web/20120110233643id_/http://www.abego-software.de:80/legal/apl-v10.html` (the licence URL named by the TreeLayout 1.0.3 POM) | Wayback snapshot `20120110233643` | `739ce194643e13015a29fb61567edad3dd80dd4df94a73ebefbd7d4606133164` |
+| `ICU-72.1.txt` | `https://github.com/unicode-org/icu/blob/ff3514f257ea10afe7e710e9f946f68d256704b1/icu4j/main/shared/licenses/LICENSE` (tag `release-72-1`) | commit `ff3514f257ea10afe7e710e9f946f68d256704b1` | `af3e84c401f1a35e8d32d6eb1a33fe587c3981aa5cd206033d9527c1855b57a2` |
+| `pgvector-0.8.6.txt` | `https://github.com/pgvector/pgvector/blob/8ee86c96f0fd72390f890aa8a336fda6d3ab4c6c/LICENSE` (tag `v0.8.6`) | commit `8ee86c96f0fd72390f890aa8a336fda6d3ab4c6c` | `6bba9ebeb73e27477463b05e5ef1bf303bccbddb3db9bbc95905d351604d6a87` |
+| `PostgreSQL-18.6.txt` | `https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/COPYRIGHT` (tag `REL_18_6`) | commit `724edf9bde9d356724ad384a2e196edc3c9f80f7` | `3d6af92ff8a4c2cdf69afb1cf44edea727922f5cd0cf8b5f72b11cdecac8fdfd` |
+| `PostGIS-3.6.4-LICENSE.txt` | `https://github.com/postgis/postgis/blob/94d984bd083635c1d253db0f87cf80b32548e406/LICENSE.TXT` (tag `3.6.4`) | commit `94d984bd083635c1d253db0f87cf80b32548e406` | `81749eea887e78402c9b85896cd629b155bc29256927f818f01001f038146391` |
+| `PostGIS-3.6.4-COPYING.txt` | `https://github.com/postgis/postgis/blob/94d984bd083635c1d253db0f87cf80b32548e406/COPYING` (tag `3.6.4`) | commit `94d984bd083635c1d253db0f87cf80b32548e406` | `8177f97513213526df2cf6184d8ff986c675afb514d4e68a404010521b880643` |

pietto-0.1.1/LICENSES/pgvector-0.8.6.txt

@@ -0,0 +1,20 @@
+Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
+
+Portions Copyright (c) 1994, The Regents of the University of California
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement
+is hereby granted, provided that the above copyright notice and this
+paragraph and the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
+DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
+DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
+ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
+PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

pietto-0.1.1/PKG-INFO

@@ -0,0 +1,411 @@
+Metadata-Version: 2.4
+Name: pietto
+Version: 0.1.1
+Summary: A gradual, semantic SQL authoring DSL
+Keywords: sql,dsl,compiler,postgresql,mysql
+Author: Mianli Wang
+Author-email: Mianli Wang <mianli.wang@mail.utoronto.ca>
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSES/ANTLR-4.13.2-Python3-template-header.txt
+License-File: LICENSES/ANTLR-4.13.2.txt
+License-File: LICENSES/PostgreSQL-18.6.txt
+License-File: LICENSES/SOURCES.md
+License-File: LICENSES/pgvector-0.8.6.txt
+License-File: THIRD_PARTY_NOTICES.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Compilers
+Requires-Dist: antlr4-python3-runtime==4.13.2
+Requires-Dist: pyarrow==25.0.1 ; extra == 'arrow'
+Requires-Dist: pyarrow==25.0.1 ; extra == 'execute-mysql'
+Requires-Dist: mysql-connector-python==26.7.0 ; extra == 'execute-mysql'
+Requires-Dist: pyarrow==25.0.1 ; extra == 'execute-postgres'
+Requires-Dist: psycopg[binary]==3.3.5 ; extra == 'execute-postgres'
+Requires-Dist: pyarrow==25.0.1 ; extra == 'execute-postgres-adbc'
+Requires-Dist: adbc-driver-postgresql==1.12.0 ; extra == 'execute-postgres-adbc'
+Requires-Dist: adbc-driver-manager==1.12.0 ; extra == 'execute-postgres-adbc'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/MianliWang/pietto
+Project-URL: Repository, https://github.com/MianliWang/pietto
+Project-URL: Documentation, https://github.com/MianliWang/pietto/tree/v0.1.1/docs
+Project-URL: Issues, https://github.com/MianliWang/pietto/issues
+Project-URL: Releases, https://github.com/MianliWang/pietto/releases
+Provides-Extra: arrow
+Provides-Extra: execute-mysql
+Provides-Extra: execute-postgres
+Provides-Extra: execute-postgres-adbc
+Description-Content-Type: text/markdown
+
+# Pietto
+
+[![CI](https://github.com/MianliWang/pietto/actions/workflows/ci.yml/badge.svg)](https://github.com/MianliWang/pietto/actions/workflows/ci.yml)
+![Python 3.12 and 3.13](https://img.shields.io/badge/Python-3.12%20%7C%203.13-3776AB?logo=python&logoColor=white)
+![Package version 0.1.1](https://img.shields.io/badge/package-0.1.1-6f42c1)
+
+Readable, typed SQL authoring with deterministic compilation.
+
+Pietto is a gradual semantic SQL authoring DSL. It parses and checks readable,
+indentation-based source, builds immutable compiler facts, and emits explicitly
+selected PostgreSQL or MySQL SQL. It does not connect to a database or execute
+SQL. PostgreSQL is the public Python SQL emitter; MySQL is available through
+explicit CLI lowering with a private emitter surface.
+
+**Status: 0.1.1 public preview.** Pietto 0.1.1 can be installed from PyPI with
+`pip install pietto` and is also attached to a
+[GitHub pre-release](https://github.com/MianliWang/pietto/releases/tag/v0.1.1).
+It has the same compiler and CLI as 0.1.0 and adds PyPI packaging information.
+The compiler and CLI described below are the public surface; database execution
+and result APIs are not public yet.
+
+## What Pietto provides
+
+- Typed shapes, sources, tables, queries, computed fields, aggregates,
+  grouping, and bounded window expressions.
+- Deterministic parser, semantic, and backend diagnostics with source locations
+  where the relevant stage has them.
+- Single-file `check`, `explain`, and `emit-sql` commands, with applicable JSON
+  output.
+- Explicit-project `emit-sql` for one selected table or query, one selected
+  dialect and an explicit emission contract, producing the versioned
+  `pietto.sql-emission.v1` artifact.
+- Deterministic project checking from an explicit `pietto.toml` root, including
+  legacy-flat projects and the current explicit-module foundation.
+- Compile-time validation and fail-closed lowering for unsupported syntax,
+  semantics, and backend capability.
+
+The compiler has no runtime evaluation, database connection, transaction
+management, scheduler, or arbitrary I/O language features.
+
+## Install
+
+Install Pietto from PyPI into a virtual environment with CPython 3.12 or later
+(replace `python3.12` with your interpreter):
+
+```bash
+python3.12 -m venv pietto-env
+pietto-env/bin/python -m pip install pietto
+pietto-env/bin/pietto --version
+```
+
+The optional extras described below install the same way, for example
+`pietto-env/bin/python -m pip install "pietto[arrow]"`.
+
+The wheel and the sdist are also attached to the
+[v0.1.1 release](https://github.com/MianliWang/pietto/releases/tag/v0.1.1). To
+install the wheel from there instead:
+
+```bash
+pietto-env/bin/python -m pip install "https://github.com/MianliWang/pietto/releases/download/v0.1.1/pietto-0.1.1-py3-none-any.whl"
+```
+
+The release lists the SHA-256 of the wheel and the sdist in `SHA256SUMS`. To
+check manually downloaded files, keep their names and run
+`sha256sum --ignore-missing -c SHA256SUMS` in the download directory. GitHub
+also offers automatic "Source code" archives; the tar.gz one downloads under the
+same name, `pietto-0.1.1.tar.gz`, but it is a snapshot of the repository, not
+the sdist, and it is not listed in `SHA256SUMS`. This
+preview was verified with CPython 3.12 and 3.13 on Linux x86-64; other
+platforms and Python versions are not covered by this evidence. With Pietto
+installed, run the commands below with `pietto-env/bin/pietto` (or activate the
+environment) instead of `uv run pietto`.
+
+## Install from a checkout
+
+Pietto requires Python 3.12 or later and uses a locked `uv` environment:
+
+```bash
+uv sync --locked
+uv run pietto --version
+uv run pietto --help
+```
+
+### Optional Arrow interoperability
+
+The core compiler and CLI need no PyArrow. The `pietto[arrow]` selector
+selects exactly `pyarrow==25.0.1`; the execution extras
+below add one database route's pinned drivers.
+From this checkout, install it into a separate environment:
+
+```bash
+uv venv /tmp/pietto-arrow
+uv pip install --python /tmp/pietto-arrow/bin/python ".[arrow]"
+```
+
+Or build and select the extra on that exact local wheel:
+
+```bash
+uv build --wheel
+uv pip install --python /tmp/pietto-arrow/bin/python "./dist/pietto-0.1.1-py3-none-any.whl[arrow]"
+```
+
+For a core-only wheel install, omit `[arrow]` and use a fresh environment.
+These are checkout/local-wheel instructions; from PyPI, install
+`"pietto[arrow]"` as shown above.
+Package and CLI version are **0.1.1**. The verified optional-extra matrix
+is **CPython 3.12 and 3.13, Linux x86-64, PyArrow 25.0.1**; other platforms,
+interpreters and Arrow versions are not covered by this evidence.
+Phase67 result APIs remain private under `pietto._project`; installing the
+extra only makes the dependency available. Public result APIs belong to
+Phase69, and the extra does not enable database execution.
+The [Phase67 audit and handoff](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/phases/phase-67/completion-audit.md) records
+the evidence layers, supported boundaries and remaining execution obligations.
+
+### Execution extras
+
+Each private execution route has its own selector; each includes the Arrow pin
+because captured results are Arrow IPC:
+
+| Selector | Adds |
+| --- | --- |
+| `pietto[execute-postgres]` | `psycopg[binary]==3.3.5` (PostgreSQL rows) |
+| `pietto[execute-mysql]` | `mysql-connector-python==26.7.0` (MySQL rows) |
+| `pietto[execute-postgres-adbc]` | `adbc-driver-postgresql==1.12.0`, `adbc-driver-manager==1.12.0` (PostgreSQL ADBC) |
+
+Saved-result use without any database driver needs only `pietto[arrow]`.
+Selectors combine, for example
+`"pietto[execute-postgres,execute-mysql]"`.
+Installing an extra never selects a route, grants execution, opens a source or
+qualifies storage. A selected route whose pinned driver is absent refuses with
+`EXECUTION_DEPENDENCY_MISSING` before any connection, another version refuses
+with that route's version error, and another route's installed driver is never
+used instead. These extras were verified on CPython 3.13.13, Linux x86-64,
+with the lock's exact artifacts; other platforms, interpreters and driver
+versions are not covered. Execution APIs remain private under `pietto._project`.
+
+## Quick start
+
+Create `active_users.pietto`:
+
+```pietto
+shape User:
+    id: UUID not null
+    email: Text nullable
+    email_norm: Text nullable
+    deleted_at: Timestamp nullable
+
+source users: User is postgres.table("users")
+
+table active_users:
+    from users
+    where deleted_at is null
+    select:
+        id
+        email
+        email_norm = lower(trim(email))
+```
+
+Check it:
+
+```bash
+uv run pietto check active_users.pietto
+uv run pietto check active_users.pietto --format json
+```
+
+Explain its semantic metadata:
+
+```bash
+uv run pietto explain active_users.pietto
+uv run pietto explain active_users.pietto --format json
+```
+
+Generate PostgreSQL SQL:
+
+```bash
+uv run pietto emit-sql active_users.pietto --dialect postgres
+```
+
+`check` does not generate or execute SQL. `emit-sql` writes SQL to stdout by
+default and can atomically replace an explicitly selected regular output file.
+
+## Projects
+
+Project commands use an explicit root containing `pietto.toml`:
+
+```text
+demo-project/
+├── pietto.toml
+└── models/
+    └── active_users.pietto
+```
+
+For the available legacy-flat project mode:
+
+```toml
+schema_version = 1
+
+[sources]
+include = ["models/*.pietto"]
+```
+
+Then run:
+
+```bash
+uv run pietto check --project demo-project
+```
+
+Project input selection and diagnostics are deterministic. Project checking is
+not SQL generation; project SQL emission is a separate explicit command.
+
+## Project SQL emission
+
+`emit-sql --project` compiles one explicitly selected `table` or `query` of an
+explicit-module project into the versioned `pietto.sql-emission.v1` artifact
+for one explicitly selected dialect. The physical relation and column names,
+storage types and value premises come from an emission contract you write for
+your database; the compiler never connects to it.
+
+```text
+demo-emit/
+├── pietto.toml
+├── main.pietto
+└── contract.json
+```
+
+`pietto.toml` selects the explicit-module project mode:
+
+```toml
+schema_version = 2
+
+[sources]
+include = ["*.pietto"]
+```
+
+`main.pietto`:
+
+```pietto
+shape Item:
+    id: Int not null
+    label: Text not null
+
+source items: Item is postgres.table("fixture.items")
+
+table active_items:
+    from items
+    select:
+        id
+        label
+```
+
+`contract.json` maps the logical source `items` to the physical relation
+`fixture.items` and each field to its column and representation:
+
+```json
+{
+  "format": "pietto.emission-contract.v1",
+  "target": {"family": "postgres", "release": "18.6"},
+  "sources": [{
+    "selector": {"module": "main.pietto", "kind": "source", "name": "items"},
+    "relation": {"namespace": "fixture", "name": "items"},
+    "scan": "relation_rows",
+    "fields": [
+      {"ordinal": 0, "name": "id", "column": "item_id",
+       "representation": {"storage": {"kind": "pg_int8"}, "nullable": false,
+                          "domain": {"kind": "int_range", "min": "0", "max": "100"}}},
+      {"ordinal": 1, "name": "label", "column": "item_label",
+       "representation": {"storage": {"kind": "pg_text"}, "nullable": false,
+                          "domain": {"kind": "text", "max_characters": 64,
+                                     "encoding": "UTF8", "collation": "C",
+                                     "padding": "NO PAD"}}}
+    ],
+    "premises": [
+      {"key": "row_domain_matches", "scope": "source", "value": true},
+      {"key": "read_only_object", "scope": "source", "value": true}
+    ]
+  }],
+  "environment": [
+    {"key": "client_encoding", "scope": "statement", "value": "UTF8"},
+    {"key": "operator_environment", "scope": "statement", "value": "builtin_only"}
+  ]
+}
+```
+
+Emit the artifact as JSON on stdout (`--format json` and
+`--literal-policy preserve` are the defaults; the contract path is relative to
+the project root):
+
+```bash
+uv run pietto emit-sql --project demo-emit --module main.pietto --kind table \
+    --name active_items --dialect postgres --emission-contract contract.json
+```
+
+Show the readable presentation on stdout and atomically write the same JSON
+artifact to a file:
+
+```bash
+uv run pietto emit-sql --project demo-emit --module main.pietto --kind table \
+    --name active_items --dialect postgres --emission-contract contract.json \
+    --format text --output active_items.sql-emission.json
+```
+
+Exit codes are `0` for a VERIFIED artifact, `1` for BLOCKED (typed blockers or
+project diagnostics) and `2` for INPUT_REJECTED (usage, project, contract or
+output errors); failures carry no candidate SQL. A `--literal-policy bind-safe`
+artifact must be consumed together with its `fixed_values` and
+`parameter_uses`; its SQL alone is not a complete statement. The complete
+contract is the
+[Slice13 specification](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/phase66-slice13-project-emit-sql-cli-explicit-contract-atomic-output-v1.md).
+
+## Documentation
+
+- [Language](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/language.md)
+- [Project and package](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/project-package.md)
+- [Development](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/development.md)
+- [Roadmap](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/roadmap.md)
+- [Status](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/status.md)
+
+Public contracts:
+
+- [CLI JSON v1](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/cli-json-v1.md)
+- [Diagnostics](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/diagnostics.md)
+- [Project JSON v2](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/project-cli-json-v2.md)
+- [Semantic metadata artifact v1](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/semantic-metadata-artifact-v1.md)
+- [Configuration](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/pietto-config-v1.md)
+- [Golden fixture policy](https://github.com/MianliWang/pietto/blob/v0.1.1/docs/spec/golden-fixture-policy-v1.md)
+
+## Development
+
+Run the authoritative local validation suite with:
+
+```bash
+uv run python scripts/validate.py
+```
+
+The normal implementation loop is focused tests, Ruff, and targeted type
+checking. Natural CI runs the final Python 3.12 and 3.13 validation coverage.
+
+## Direction
+
+Pietto is an early preview. These are the goals it is working toward; they are
+not promises or dates, and the detailed plan lives in the
+[roadmap](https://github.com/MianliWang/pietto/blob/main/docs/roadmap.md).
+
+- **Everyday SQL**: CASE, CAST, COALESCE/NULLIF, IN lists, NOT, LIKE, and common
+  string, number and date functions.
+- **Real-world column types end to end**: timestamps, UUIDs, decimals, dates and
+  times, then arrays and nested records.
+- **Richer queries**: subqueries and `WITH`, EXISTS/IN, VALUES and table functions.
+- **Richer aggregation**: SUM and AVG in project SQL emission, FILTER,
+  statistical aggregates, grouping extensions and aggregates as window
+  functions.
+- **Run queries safely from Python**: compile, execute through an explicit
+  database driver, and get typed Arrow results.
+- **Data tools**: pandas, Polars and NumPy interoperability.
+- **More databases**: deeper PostgreSQL and MySQL support, then SQLite and DuckDB.
+- **Tooling**: a formatter, language-server and editor support, clearer diagnostics.
+- **Stability**: a 1.0 release with frozen syntax, CLI and APIs.
+
+## License
+
+Pietto is released under the
+[MIT License](https://github.com/MianliWang/pietto/blob/v0.1.1/LICENSE).
+Third-party material in the wheel, the sdist and the source archive is listed
+in [THIRD_PARTY_NOTICES.md](https://github.com/MianliWang/pietto/blob/v0.1.1/THIRD_PARTY_NOTICES.md),
+with the original license texts in
+[LICENSES/](https://github.com/MianliWang/pietto/tree/v0.1.1/LICENSES).