@delma/fylo 1.0.0

package/.env.example

@@ -0,0 +1,16 @@
+LOGGING=
+STRICT=
+S3_REGION=ca-central-1
+S3_ACCESS_KEY_ID=HELLO
+S3_SECRET_ACCESS_KEY=WORLD
+S3_ENDPOINT=https//example.com
+BUCKET_PREFIX="byos-test"
+SCHEMA_DIR=/path/to/schema/dir
+REDIS_URL=redis://localhost:6379
+REDIS_CONN_TIMEOUT=5000
+REDIS_IDLE_TIMEOUT=30000
+REDIS_AUTO_RECONNECT=
+REDIS_MAX_RETRIES=10
+REDIS_ENABLE_OFFLINE_QUEUE=
+REDIS_ENABLE_AUTO_PIPELINING=
+REDIS_TLS=

package/.github/copilot-instructions.md

@@ -0,0 +1,113 @@
+# FYLO — Project Guidelines
+
+## Overview
+
+FYLO (`@vyckr/fylo`) is an S3-backed NoSQL document store with SQL parsing, Redis pub/sub for real-time events, and a CLI. Documents are stored as S3 key paths — not as file contents — with dual key layouts for data access and indexed queries.
+
+**Assume a serverless deployment model** (e.g., AWS Lambda, Cloudflare Workers). This means:
+- No persistent in-memory state across invocations — every request starts cold
+- Distributed coordination (e.g., TTID uniqueness) must use external stores like Redis, not in-process caches
+- Avoid long-lived connections, background threads, or singleton patterns that assume process longevity
+- Keep cold-start overhead minimal — lazy initialization over eager setup
+
+## Architecture
+
+### Key Storage Format
+
+- **Data keys**: `{ttid}/{field}/{value}` — keyed by document ID for full-doc retrieval
+- **Index keys**: `{field}/{value}/{ttid}` — keyed by field for query lookups
+- Nested objects flatten to path segments: `address/city/Toronto`
+- Forward slashes in values are escaped with an ASCII substitute
+
+### Core Modules
+
+| Module | Responsibility |
+|--------|---------------|
+| `src/index.ts` | Main `Fylo` class — CRUD, SQL execution, joins, bulk ops |
+| `src/core/parser.ts` | SQL lexer/parser — tokenizes SQL into query objects |
+| `src/core/query.ts` | Converts `$ops` into glob patterns for S3 key matching |
+| `src/core/walker.ts` | S3 key traversal, document data retrieval, Redis event streaming |
+| `src/core/directory.ts` | Key extraction, reconstruction, rollback tracking |
+| `src/core/format.ts` | Console formatting for query output |
+| `src/adapters/s3.ts` | S3 adapter (Bun S3Client) |
+| `src/adapters/redis.ts` | Redis adapter (Bun RedisClient) |
+| `src/cli/index.ts` | CLI entry point (`fylo.query`) |
+
+### Folder Structure
+
+```
+src/
+  index.ts                # Public API — main Fylo class
+  adapters/               # I/O boundary abstractions (S3, Redis)
+  core/                   # Internal domain logic (parser, query, walker, directory)
+  cli/                    # CLI entry point
+  types/                  # Type declarations (.d.ts only — separate from implementation)
+tests/
+  data.ts                 # Shared test data URLs
+  index.ts                # Test barrel
+  mocks/                  # Mock adapters (S3, Redis) for testing
+  schemas/                # CHEX-generated test schemas (.d.ts + .json)
+  integration/            # End-to-end tests (CRUD, operators, joins, edge cases)
+```
+
+### Dependencies
+
+- **`@vyckr/ttid`** — Time-based unique ID system. `TTID.generate()` creates new IDs; `TTID.generate(existingId)` creates a versioned ID sharing the same creation-time prefix.
+- **`@vyckr/chex`** — Schema validation. Generates `interface` declarations in `.d.ts` files. Generic constraints must use `Record<string, any>` (not `Record<string, unknown>`) to accept these interfaces.
+- **`Bun.Glob`** — Pattern matching for queries. Does NOT support negation extglob `!(pattern)`. Operators like `$ne`, `$gt`, `$lt` use broad globs with post-filtering instead.
+
+## Engineering Standards
+
+- **SOLID principles**: Single responsibility per class/method, depend on abstractions (e.g., S3/Redis adapters), open for extension without modifying core logic
+- **Clean code**: Descriptive naming, small focused functions, no dead code or commented-out blocks, DRY without premature abstraction
+- **Test discipline**: When changing `src/` code, update or add corresponding tests in `tests/` — never leave tests stale after a behaviour change
+- **Error handling**: Fail fast with meaningful errors at system boundaries; use rollback mechanisms for partial writes
+- **No magic values**: Use constants or environment variables; avoid hardcoded strings/numbers in logic
+- **Type safety**: Leverage TypeScript's type system fully — avoid `any` in implementation code, prefer narrow types, and validate at I/O boundaries
+
+## Code Style
+
+- **Runtime**: Bun (ESNext target, ES modules)
+- **Strict TypeScript**: `strict: true`, `noImplicitReturns`, `isolatedModules`
+- **ESLint** enforces `@typescript-eslint/no-explicit-any` in `src/` and `tests/` — use it only in type declarations (`.d.ts`)
+- **No default exports** except the main `Fylo` class
+- Prefer `class` with `static` methods for modules (no standalone functions)
+- Use `_ttid` branded type for document IDs — never plain `string`
+- Prefix internal/test type names with underscore: `_post`, `_album`, `_storeQuery`
+- Type declarations live in `src/types/*.d.ts` — keep separate from implementation
+
+## Build & Test
+
+```bash
+bun test           # Run all tests
+bun run build      # Compile TypeScript
+bun run typecheck  # Type-check without emitting
+bun run lint       # ESLint
+```
+
+- Tests use `bun:test` — `describe`, `test`, `expect`, `mock`, `beforeAll`, `afterAll`
+- S3 and Redis are mocked via `mock.module()` in every test file using `tests/mocks/s3.ts` and `tests/mocks/redis.ts`
+- Test schemas live in `tests/schemas/*.d.ts` as global `interface` declarations (generated by CHEX)
+- Test data URLs are centralized in `tests/data.ts`
+
+## Conventions
+
+- Collection names may contain hyphens (e.g., `ec-test`, `jm-album`) — the parser supports this
+- Nested field access in SQL uses dot notation (`address.city`) which the parser converts to slash-separated paths (`address/city`)
+- `putData` creates documents; `patchDoc` updates them (deletes old keys, writes new ones)
+- `getDocData` retrieves keys for a specific TTID — filters by exact ID, not just prefix
+- Query `$ops` use OR semantics — a document matches if it satisfies at least one operator
+- `$limit` on queries without `$ops` uses S3 `maxKeys`; with `$ops` it post-filters after glob matching
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BUCKET_PREFIX` | S3 bucket name prefix |
+| `S3_ACCESS_KEY_ID` / `AWS_ACCESS_KEY_ID` | S3 credentials |
+| `S3_SECRET_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY` | S3 credentials |
+| `S3_REGION` / `AWS_REGION` | S3 region |
+| `S3_ENDPOINT` / `AWS_ENDPOINT` | S3 endpoint (for compatible stores) |
+| `REDIS_URL` | Redis connection URL |
+| `LOGGING` | Enable debug logging |
+| `STRICT` | Enable schema validation via CHEX |

package/.github/prompts/issue.prompt.md

@@ -0,0 +1,19 @@
+---
+description: "Create a GitHub issue for a bug or feature request"
+argument-hint: "Describe the bug or feature request"
+agent: "agent"
+tools: [runInTerminal]
+---
+Create a GitHub issue. The user's description is provided as the argument.
+
+Determine whether the description sounds like a bug or a feature request, then create the issue with `gh issue create` using the following structure:
+
+**For a bug:**
+- Title: "fix: <short description>"
+- Body sections: **Describe the bug**, **Steps to reproduce**, **Expected behaviour**, **Actual behaviour**, **Possible cause** (reference relevant lines in `src/index.ts` if applicable), **Environment** (Bun version, TypeScript version, AWS/S3 endpoint details).
+
+**For a feature request:**
+- Title: "feat: <short description>"
+- Body sections: **Problem**, **Proposed solution**, **Alternatives considered**, **Affected API** (list any methods in `src/types/fylo.d.ts` or `src/types/query.d.ts` that would change).
+
+Apply the appropriate label (`bug` or `enhancement`) via `--label`. Print the issue URL when done.

package/.github/prompts/pr.prompt.md

@@ -0,0 +1,18 @@
+---
+description: "Create a pull request for the current branch into main"
+agent: "agent"
+tools: [runInTerminal]
+---
+Create a pull request for the current branch into `main`.
+
+1. Run `git status` and stop if there are uncommitted changes — ask the user to commit or stash them first.
+2. Run `git log main..HEAD --oneline` to list commits on this branch.
+3. Run `git diff main...HEAD` to understand all changes.
+4. Push the branch to origin if it has no upstream: `git push -u origin HEAD`.
+5. Create the PR with `gh pr create` using:
+   - A concise title (≤ 70 chars) derived from the branch name and commits.
+   - A body with three sections:
+     - **Summary** — bullet list of what changed and why.
+     - **Test plan** — checklist of how to verify the changes (reference `bun test` where relevant).
+     - **Breaking changes** — any changes to public API in [src/types/fylo.d.ts](src/types/fylo.d.ts) or [src/types/query.d.ts](src/types/query.d.ts); write "None" if there are none.
+6. Print the PR URL.

package/.github/prompts/release.prompt.md

@@ -0,0 +1,49 @@
+---
+description: "Create a release branch, publish to npm via CI, then merge to main"
+agent: "agent"
+tools: [runInTerminal]
+---
+Create a release branch, publish to npm via CI, then merge to main.
+
+1. Run `bun test` and stop if any tests fail.
+
+2. Determine the new version automatically based on unreleased commits:
+   `git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline`
+
+   Apply these rules to select the bump type:
+   - **major** — any commit with a `!` breaking-change marker (e.g. `feat!:`, `fix!:`) or a `BREAKING CHANGE` footer.
+   - **minor** — one or more `feat:` commits and no breaking changes.
+   - **patch** — only `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, or `perf:` commits.
+
+   Compute the new version by incrementing the corresponding part of the current `"version"` in [package.json](package.json) and resetting lower parts to zero. Show the chosen version and the reasoning to the user before proceeding.
+
+3. Update `"version"` in [package.json](package.json) to the new version.
+
+4. Fetch the latest main and create a release branch from it:
+   ```
+   git fetch origin main
+   git checkout -b release/<version> origin/main
+   ```
+
+5. Stage all changes and commit:
+   `git add -A && git commit -m "chore: release v<version>"`
+
+6. Push the branch:
+   `git push -u origin release/<version>`
+
+7. Tell the user that the `publish` workflow will now run on GitHub Actions:
+   - It verifies the branch name matches `package.json` version.
+   - It runs tests, publishes to npm, creates a git tag, and opens a GitHub release.
+   - The NPM_TOKEN secret must be set in repo Settings → Secrets → Actions.
+
+8. Once the workflow passes (user confirms), create a PR and merge it to main:
+   ```
+   gh pr create --title "chore: release v<version>" --body "Release v<version>" --base main --head release/<version>
+   gh pr merge --merge --delete-branch
+   ```
+
+9. Switch back to main and pull:
+   ```
+   git checkout main
+   git pull
+   ```

package/.github/prompts/review-pr.prompt.md

@@ -0,0 +1,19 @@
+---
+description: "Review a pull request by number or URL"
+argument-hint: "PR number or URL (e.g. 42)"
+agent: "agent"
+tools: [runInTerminal]
+---
+Review the pull request given as an argument (PR number or URL).
+
+1. Fetch the PR details: `gh pr view <arg> --json title,body,headRefName,baseRefName,files`
+2. Fetch the diff: `gh pr diff <arg>`
+3. Review the changes with focus on:
+   - **Correctness** — logic errors, edge cases missed in query parsing ([src/core/parser.ts](src/core/parser.ts)), S3 operations ([src/adapters/s3.ts](src/adapters/s3.ts)), or directory/index management ([src/core/directory.ts](src/core/directory.ts)).
+   - **Type safety** — use of `any` instead of `unknown`, missing type guards, incorrect use of types in [src/types/](src/types/).
+   - **Tests** — whether new behaviour is covered in [tests/](tests/); flag any missing cases across document, collection, or schema tests.
+   - **Public API** — unintended changes to [src/types/fylo.d.ts](src/types/fylo.d.ts) or [src/types/query.d.ts](src/types/query.d.ts).
+   - **CI** — whether the workflow files in [.github/workflows/](.github/workflows/) are still valid for the change.
+4. Post the review as inline comments using `gh pr review <arg> --comment --body "<feedback>"`.
+   Group feedback by file. Prefix each point with **[suggestion]**, **[issue]**, or **[nit]**.
+5. Summarise the overall verdict: Approve / Request changes / Comment only.

package/.github/prompts/sync-main.prompt.md

@@ -0,0 +1,14 @@
+---
+description: "Rebase the current branch onto the latest main from origin"
+agent: "agent"
+tools: [runInTerminal]
+---
+Safely bring the current branch up to date with the latest `main` from origin.
+
+1. Confirm the current branch with `git branch --show-current`. If already on `main`, just run `git pull` and stop.
+2. Stash any uncommitted changes with `git stash push -m "sync-main auto-stash"` and note whether anything was stashed.
+3. Fetch the latest: `git fetch origin main`.
+4. Rebase the current branch onto `origin/main`: `git rebase origin/main`.
+5. If the rebase has conflicts, list the conflicting files and stop — ask the user to resolve them, then run `git rebase --continue`.
+6. If a stash was created in step 2, restore it with `git stash pop`.
+7. Report: commits rebased, files changed, any stash restored.

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [release/*]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Bun ${{ matrix.bun-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        bun-version: [latest, 1.2.x]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ matrix.bun-version }}
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Run tests
+        run: bun test

package/.github/workflows/publish.yml

@@ -0,0 +1,101 @@
+name: Publish
+
+on:
+  push:
+    branches: [release/*]
+
+jobs:
+  test:
+    name: Test before publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Run tests
+        run: bun test
+
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: write   # create git tags
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Setup Node and upgrade npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Upgrade npm
+        run: npm install -g npm@latest
+
+      - name: Resolve version from branch
+        id: version
+        run: |
+          BRANCH="${GITHUB_REF#refs/heads/}"
+          VERSION="${BRANCH#release/}"
+          PKG_VERSION=$(bun -e "console.log(require('./package.json').version)")
+          if [ "$VERSION" != "$PKG_VERSION" ]; then
+            echo "Branch version ($VERSION) does not match package.json ($PKG_VERSION). Skipping publish."
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Verify NPM token
+        run: |
+          if [ -z "${NPM_TOKEN}" ]; then
+            echo "NPM_TOKEN secret is not configured."
+            exit 1
+          fi
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish to npm
+        run: |
+          npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create and push version tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -f -a "v${{ steps.version.outputs.version }}" -m "v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}" --force
+
+      - name: Create GitHub release
+        run: |
+          gh release create "v${{ steps.version.outputs.version }}" \
+            --title "v${{ steps.version.outputs.version }}" \
+            --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+    "semi": false,
+    "singleQuote": true,
+    "tabWidth": 4,
+    "trailingComma": "none",
+    "printWidth": 100
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyckr
+
+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.

package/README.md

@@ -0,0 +1,230 @@
+# Fylo
+
+S3-backed NoSQL document store with SQL parsing, Redis pub/sub for real-time events, and a CLI.
+
+Documents are stored as **S3 key paths** — not file contents. Each document produces two keys per field: a **data key** (`{ttid}/{field}/{value}`) for full-doc retrieval and an **index key** (`{field}/{value}/{ttid}`) for query lookups. This enables fast reads and filtered queries without a traditional database engine.
+
+Built for **serverless** runtimes (AWS Lambda, Cloudflare Workers) — no persistent in-memory state, lazy connections, minimal cold-start overhead.
+
+## Install
+
+```bash
+bun add @vyckr/fylo
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BUCKET_PREFIX` | S3 bucket name prefix |
+| `S3_ACCESS_KEY_ID` / `AWS_ACCESS_KEY_ID` | S3 credentials |
+| `S3_SECRET_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY` | S3 credentials |
+| `S3_REGION` / `AWS_REGION` | S3 region |
+| `S3_ENDPOINT` / `AWS_ENDPOINT` | S3 endpoint (for LocalStack, MinIO, etc.) |
+| `REDIS_URL` | Redis connection URL (default: `redis://localhost:6379`) |
+| `LOGGING` | Enable debug logging |
+| `STRICT` | Enable schema validation via CHEX |
+
+## Usage
+
+### CRUD — NoSQL API
+
+```typescript
+import Fylo from "@vyckr/fylo"
+
+const fylo = new Fylo()
+
+// Collections
+await Fylo.createCollection("users")
+
+// Create
+const _id = await fylo.putData<_user>("users", { name: "John Doe", age: 30 })
+
+// Read one
+const user = await Fylo.getDoc<_user>("users", _id).once()
+
+// Read many
+for await (const doc of Fylo.findDocs<_user>("users", { $limit: 10 }).collect()) {
+    console.log(doc)
+}
+
+// Update one
+await fylo.patchDoc<_user>("users", { [_id]: { age: 31 } })
+
+// Update many
+const updated = await fylo.patchDocs<_user>("users", {
+    $where: { $ops: [{ age: { $gte: 30 } }] },
+    $set: { age: 31 }
+})
+
+// Delete one
+await fylo.delDoc("users", _id)
+
+// Delete many
+const deleted = await fylo.delDocs<_user>("users", {
+    $ops: [{ name: { $like: "%Doe%" } }]
+})
+
+// Drop
+await Fylo.dropCollection("users")
+```
+
+### CRUD — SQL API
+
+```typescript
+const fylo = new Fylo()
+
+await fylo.executeSQL(`CREATE TABLE users`)
+
+const _id = await fylo.executeSQL<_user>(`INSERT INTO users (name, age) VALUES ('John Doe', 30)`)
+
+const docs = await fylo.executeSQL<_user>(`SELECT * FROM users LIMIT 10`)
+
+await fylo.executeSQL<_user>(`UPDATE users SET age = 31 WHERE name = 'John Doe'`)
+
+await fylo.executeSQL<_user>(`DELETE FROM users WHERE name LIKE '%Doe%'`)
+
+await fylo.executeSQL(`DROP TABLE users`)
+```
+
+### Query Operators
+
+```typescript
+// Equality
+{ $ops: [{ status: { $eq: "active" } }] }
+
+// Not equal
+{ $ops: [{ status: { $ne: "archived" } }] }
+
+// Numeric range
+{ $ops: [{ age: { $gte: 18, $lt: 65 } }] }
+
+// Pattern matching
+{ $ops: [{ email: { $like: "%@gmail.com" } }] }
+
+// Array contains
+{ $ops: [{ tags: { $contains: "urgent" } }] }
+
+// Multiple ops use OR semantics — matches if any op is satisfied
+{ $ops: [
+    { status: { $eq: "active" } },
+    { priority: { $gte: 5 } }
+]}
+```
+
+### Joins
+
+```typescript
+const results = await Fylo.joinDocs<_post, _user>({
+    $leftCollection: "posts",
+    $rightCollection: "users",
+    $mode: "inner",       // "inner" | "left" | "right" | "outer"
+    $on: { userId: { $eq: "id" } },
+    $select: ["title", "name"],
+    $limit: 50
+})
+```
+
+### Real-Time Streaming
+
+```typescript
+// Stream new/updated documents
+for await (const doc of Fylo.findDocs<_user>("users")) {
+    console.log(doc)
+}
+
+// Stream deletions
+for await (const _id of Fylo.findDocs<_user>("users").onDelete()) {
+    console.log("deleted:", _id)
+}
+
+// Watch a single document
+for await (const doc of Fylo.getDoc<_user>("users", _id)) {
+    console.log(doc)
+}
+```
+
+### Bulk Import / Export
+
+```typescript
+const fylo = new Fylo()
+
+// Import from JSON array or NDJSON URL
+const count = await fylo.importBulkData<_user>("users", new URL("https://example.com/users.json"), 1000)
+
+// Export all documents
+for await (const doc of Fylo.exportBulkData<_user>("users")) {
+    console.log(doc)
+}
+```
+
+### Rollback
+
+Every write is tracked as a transaction. If a batch write partially fails, Fylo automatically rolls back. You can also trigger it manually:
+
+```typescript
+const fylo = new Fylo()
+await fylo.putData("users", { name: "test" })
+await fylo.rollback() // undoes all writes in this instance
+```
+
+### CLI
+
+```bash
+fylo.query "SELECT * FROM users WHERE age > 25 LIMIT 10"
+```
+
+### Schema Validation
+
+When `STRICT` is set, documents are validated against CHEX schemas before writes:
+
+```bash
+STRICT=true bun run start
+```
+
+Schemas are `.d.ts` interface declarations generated by [`@vyckr/chex`](https://github.com/vyckr/chex).
+
+## Development
+
+```bash
+bun test           # Run all tests
+bun run build      # Compile TypeScript
+bun run typecheck  # Type-check without emitting
+bun run lint       # ESLint
+```
+
+### Local S3 (LocalStack)
+
+```bash
+docker compose up aws
+```
+
+This starts LocalStack on `localhost:4566`. Set `S3_ENDPOINT=http://localhost:4566` to route S3 calls locally.
+
+## Security
+
+### What Fylo does NOT provide
+
+Fylo is a low-level storage abstraction. The following must be implemented by the integrating application:
+
+- **Authentication** — Fylo has no concept of users or sessions. Any caller with access to the Fylo instance can read and write any collection.
+- **Authorization** — `executeSQL` and all document operations accept any collection name with no permission check. In multi-tenant applications, a caller can access any collection unless the integrator enforces a boundary above Fylo.
+- **Rate limiting** — There is no built-in request throttling. An attacker with access to the instance can flood S3 with requests or trigger expensive operations without restriction. Add rate limiting and document-size limits in your service layer.
+
+### Secure configuration
+
+| Concern | Guidance |
+|---------|----------|
+| AWS credentials | Never commit credentials to version control. Use IAM instance roles or inject via CI secrets. Rotate any credentials that have been exposed. |
+| `ENCRYPTION_KEY` | Must be at least 32 characters. Use a high-entropy random value. |
+| `CIPHER_SALT` | Set a unique random value per deployment to prevent cross-instance precomputation attacks. |
+| `REDIS_URL` | Always set explicitly. Use `rediss://` (TLS) in production with authentication credentials in the URL. |
+| Collection names | Must match `^[a-z0-9][a-z0-9\-]*[a-z0-9]$`. Names are validated before any shell or S3 operation. |
+
+### Encrypted fields
+
+Fields listed in `$encrypted` in a collection schema are encrypted with AES-256-CBC. By default a random IV is used per write (non-deterministic). Pass `deterministic: true` to `Cipher.encrypt()` only for fields that require `$eq`/`$ne` queries — deterministic encryption leaks value equality to observers of stored ciphertext.
+
+## License
+
+MIT