Establish Zagkit product and master goal contract

.gitattributes

@@ -0,0 +1,4 @@
+*.zag text eol=lf
+*.md text eol=lf
+*.json text eol=lf
+*.sh text eol=lf

.github/workflows/contracts.yml

@@ -0,0 +1,53 @@
+name: Repository contracts
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      ZNC: ${{ github.workspace }}/.toolchain/zag/zag-poc/znc
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+      - name: Resolve pinned Zag revision
+        id: toolchain
+        run: echo "zag_sha=$(jq -r '.zag.commit' contracts/toolchain.json)" >> "$GITHUB_OUTPUT"
+      - name: Check out pinned Zag toolchain
+        uses: actions/checkout@v6
+        with:
+          repository: Sylorlabs/zag
+          ref: ${{ steps.toolchain.outputs.zag_sha }}
+          path: .toolchain/zag
+      - name: Restore fixed-point Zag compiler
+        id: zag-cache
+        uses: actions/cache@v5
+        with:
+          path: |
+            .toolchain/zag/zag-poc/znc
+            .toolchain/zag/zag-poc/zagd
+          key: zag-fixed-${{ runner.os }}-${{ steps.toolchain.outputs.zag_sha }}
+      - name: Bootstrap pinned Zag source
+        if: steps.zag-cache.outputs.cache-hit != 'true'
+        run: |
+          chmod +x .toolchain/zag/zag-poc/znc .toolchain/zag/zag-poc/bootstrap.sh
+          ZAG_BOOTSTRAP_MEMORY_GUARD=off .toolchain/zag/zag-poc/bootstrap.sh
+      - name: Run strict headless contracts
+        env:
+          ZNC: ${{ github.workspace }}/.toolchain/zag/zag-poc/znc
+        run: |
+          chmod +x "$ZNC"
+          ./tools/test-headless.sh
+      - name: Smoke test local CLI launcher
+        run: ./tools/test-zagkit-cli.sh
+      - name: Validate product contracts
+        run: ./tools/check-contracts.sh
+      - name: Reject whitespace errors
+        run: git show --check --format= HEAD

.gitignore

@@ -0,0 +1,23 @@
+# Zag build products
+zag-out/
+.zag-cache/
+.zagd.lock
+.zagd.semantic-ready
+.zagd.status
+.zagkit/
+
+# Contract and benchmark output
+artifacts/
+benchmark-results/
+capability-reports/
+docs/evidence/*.log
+
+# Platform build products
+.DS_Store
+Thumbs.db
+*.app/
+*.apk
+*.aab
+*.ipa
+*.msix
+*.dmg

CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+Zagkit follows Semantic Versioning and keeps unreleased work under the heading
+below. Public preview labels do not imply platform support. Every release must
+include a generated capability record and exact Zag compiler revision.
+
+## Unreleased
+
+### Added
+
+- Milestone 0 product, architecture, quality, and dependency contracts.
+- Machine readable platform, component, benchmark, compiler, and upstream
+  prerequisite records.
+- An executable repository contract gate.
+- Experimental typed state and binding primitives with exact dependency-read
+  invalidation evidence.
+- Experimental keyed reconciliation with stable reorder identity and
+  fail-visible duplicate-key handling.
+- Deterministic fixed-point geometry, constraints, and single-line Flex.
+- Experimental retained intrinsic measurement for leaf, row, column, and
+  overlay trees with explicit constraint rules, priorities, baselines,
+  overflow, revision stability, ownership failures, deterministic identity,
+  and exact state-read layout invalidation causes.
+- Experimental adaptive Flex primitives with tokenized density-aware spacing,
+  physical safe areas, text-scale-aware breakpoints, deterministic row and
+  column wrapping, RTL line bands, baseline-safe extents, per-line growth,
+  typed overflow, malformed-input rejection, and layout identity.
+- An experimental owned semantics tree with roles, actions, focus order,
+  live regions, ranges, selection, text navigation, descriptions, bounds,
+  relationships, collection coordinates and counts, hierarchy, expansion, and
+  stable generated IDs.
+- Bounded virtual Table and Tree semantic projection with full logical counts,
+  exact live geometry, deterministic collection IDs, and collision-atomic
+  preflight.
+- The first in-process Zagkit Talkback dispatcher and machine-readable protocol
+  with protocol 0.2 query evidence for semantic geometry, collection metadata,
+  tree state, owned-text lengths, state flags, deterministic hashes, ID-first
+  targeting, and explicit scale-aware pixel fallback.
+- A bounded owned render-resource store with typed stable IDs, canonical order,
+  exact replacement revisions, copied payloads, byte accounting, sealing,
+  mutation detection, typed display-list reference validation, and explicit
+  decoder boundaries.
+- A canonical bounded `ZKPATH01` vector-path builder and codec with non-zero or
+  even-odd fill rules, line and curve commands, immutable identity, typed
+  display-resource validation, malformed-input offsets, and byte-identical
+  round trips.
+- Canonical decoded RGBA8 image resources with overflow-safe dimensional
+  validation, exact payload sizing, explicit color-space truth, deterministic
+  premultiplied bilinear CPU sampling, fractional-edge coverage, and opacity.
+- Deterministic PNG serialization for CPU surfaces with explicit sRGB intent,
+  exact filter-zero RGBA8 rows, CRC-checked chunks, a pure-Zag stored-zlib IDAT
+  stream, malformed-surface rejection, and byte-identical output evidence.
+- A pure-Zag persisted headless reference scene whose PNG signature, substantial
+  output, and two-run byte identity execute in the normal repository gate.
+- An experimental immutable display list for explicit paints, resources, clips,
+  transforms, layers, and effects with deterministic content identity.
+- A versioned canonical display-list codec with bounded validated decoding and
+  byte-identical replay round trips, upgraded to ZKDL version 2 with owned
+  resource metadata, payload, allocation-policy, and revision serialization.
+- The first deterministic CPU-oracle subset for fixed-point fills, clipping,
+  axis-aligned transforms, fractional coverage, and source-over alpha, extended
+  with centered analytic rectangle strokes, bounded canonical path fills,
+  quadratic and cubic flattening, non-zero and even-odd winding, 8 by 8
+  coverage, and fail-before-pixel work ceilings.
+- Strict executable headless contracts in CI using the exact pinned Zag
+  revision rather than an ambient compiler.
+- Transformed hit testing and deterministic pointer routing with clipping,
+  z-order, capture, focus, stale-target recovery, and ordered evidence.
+- A sealed deterministic replay tape and conformance executor covering exact
+  state revisions, pointer input, monotonic time, backend activation, loss,
+  recovery, and regenerated motion, semantics, measurement, Flex, display-list,
+  and CPU identities.
+- A refresh-aware deterministic motion scheduler with fixed-step integer
+  springs, owned keyframes, explicit frame reasons, interruption, reversal,
+  resize continuity, gesture velocity handoff, and semantic reduced-motion
+  substitutions that perform no continuous work after settling.
+
+## 0.1.0-experimental.0 (unreleased)
+
+The repository contract seed. No runtime or platform backend is available.

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to Zagkit
+
+Zagkit accepts narrowly scoped, evidence backed changes that preserve the
+architecture and support claims in this repository.
+
+## Before writing code
+
+1. Read [GOVERNANCE.md](GOVERNANCE.md), [DEPENDENCIES.md](DEPENDENCIES.md), and
+   the [accepted RFCs](docs/rfcs/README.md).
+2. Check [the upstream ledger](contracts/upstream-zag.json). A reusable compiler,
+   ABI, concurrency, package, or platform defect belongs in Zag first.
+3. Read the [active master goal checklist](GOAL.md) and name the stable IDs the
+   change advances. Never remove or check unrelated items.
+4. Check the visual direction gate. Visual component production cannot begin
+   until [the design review](docs/design/visual-direction.md) is accepted.
+5. Add or update the smallest contract, test, benchmark, or conformance scene
+   that can prove the change.
+
+## Change requirements
+
+- Production implementation is Zag. Do not add a C, C++, Zig, Rust, browser,
+  WebView, or foreign toolkit fallback to make a missing Zag feature disappear.
+- Do not preserve a workaround merely because it would be conventional in
+  another language ecosystem. Improve Zag until the direct design is possible.
+- Public OS APIs are permitted only at the platform seams listed in
+  [DEPENDENCIES.md](DEPENDENCIES.md).
+- A backend or feature may be `supported`, `experimental`, or `unavailable`.
+  Supported and experimental states require named executable evidence.
+- GPU work on hardware must be explicitly selected, bounded, and recoverable.
+  Discovery, compilation, screenshots, or CPU output do not certify GPU use.
+- Tests must include cleanup and negative behavior where resources, malformed
+  input, callbacks, device loss, or platform boundaries are involved.
+- Keep unrelated worktree changes out of the commit.
+- Give every actionable component and application node a stable Zagkit Talkback
+  ID; pixel fallback must be explicit, observable, and justified.
+- Use Flex semantic spacing and placement rules. Unexplained screen-local
+  offsets are defects, not polish.
+
+An upstream fix is complete only when it is committed separately in
+`/home/micah/Desktop/Sylorlabs/zag`, carries source and native executable
+conformance there, and the affected Zagkit gate passes against that exact Zag
+commit. A local Zag working tree, patched compiler binary, or downstream-only
+test is not a dependency revision.
+
+## Local gate
+
+```sh
+./tools/check-contracts.sh
+git diff --check
+```
+
+Later milestones add compiler, unit, fuzz, golden, live platform, performance,
+accessibility, and packaging gates. A green contract check does not substitute
+for any of them.
+
+## RFCs
+
+Use [RFC 0000](docs/rfcs/0000-rfc-process.md) for changes to public API,
+architecture, dependency boundaries, backend truth, or release gates. An RFC
+records a decision. It is not implementation evidence.

DEPENDENCIES.md

@@ -0,0 +1,59 @@
+# Dependency and ownership boundary
+
+Zagkit is built in Zag and owns the product layers above public operating system
+and driver seams. This policy is normative.
+
+## Zagkit owned layers
+
+- state, bindings, actions, environment, view context, and stable node identity;
+- reconciliation, layout, invalidation reasons, hit testing, and focus;
+- semantics and automation trees;
+- input routing, gestures, commands, animation, and frame scheduling;
+- Unicode processing, OpenType shaping, font fallback, editing, and glyph
+  rasterization;
+- render IR, immutable display lists, deterministic CPU rendering, GPU resource
+  ownership, and backend recovery;
+- components, design tokens, adaptive behavior, inspectors, preview, reload,
+  snapshots, and command line tools.
+
+## Allowed operating system seams
+
+Public OS and GPU APIs may provide lifecycle, windows, surfaces, vsync, GPU
+submission, IME, accessibility, clipboard, drag and drop, system menus, haptics,
+notifications, and packaging. System fonts plus published Unicode and OpenType
+data are allowed inputs.
+
+These seams must be isolated behind Zag interfaces, report capability truth,
+clean up resources, and have native conformance tests. A platform seam does not
+own Zagkit's view tree, layout, semantics, text model, or renderer architecture.
+
+## Prohibited runtime architecture
+
+The core and platform product may not depend on:
+
+- native widget proxy frameworks;
+- browser or WebView runtimes;
+- Skia, Flutter, Qt, FreeType, HarfBuzz, or another UI, text, or render engine;
+- private Apple APIs;
+- an LLVM based renderer;
+- a C, C++, Zig, Rust, or other foreign implementation shim used to hide a Zag
+  compiler or runtime gap.
+
+Host tools used only to package, sign, drive a platform SDK, or validate
+repository metadata are not runtime dependencies. They must be declared,
+versioned where practical, and cannot implement product behavior.
+
+## Source first rule
+
+A reusable Zag language, compiler, ABI, concurrency, package, platform, or
+runtime defect is fixed in the Zag repository with native conformance before
+Zagkit consumes it. Zagkit may keep a failing reproducer and dependency record,
+but not a permanent workaround. The upstream change is checked in separately,
+and Zagkit pins the exact proven commit before relying on it. Patterns that
+would normally be hidden behind a shim, reduced feature, unsafe escape, or
+ecosystem workaround in another language are still Zag defects to solve at the
+source. The authoritative queue is
+[contracts/upstream-zag.json](contracts/upstream-zag.json).
+
+Vendor driver replacement can remain experimental and does not block 1.0.
+Supported public GPU transports and the CPU visual oracle remain authoritative.