docs: OSS-readiness — English docs, samples, SECURITY/COC/CHANGELOG

.github/workflows/ci.yml

@@ -259,6 +259,41 @@ jobs:
       - name: Cada --filter documentado casa con ≥1 test
         run: bash .github/scripts/check-test-filters.sh
 
+  # ── License gate: third-party notices for the redistributed native binaries ───────────────
+  # BLOCKING. The NuGet packages ship the cdylibs, which statically link Rust crates — so their
+  # licenses are redistributed too. This job regenerates THIRD-PARTY-NOTICES.md with cargo-about
+  # and fails if (a) a dependency introduces a license not in `accepted` (native/about.toml), or
+  # (b) the committed notice is stale. Keeps the attribution honest as the dependency tree moves
+  # (e.g. a yrs/Loro bump, FU-015). cargo-about is pinned for reproducible output.
+  third-party-notices:
+    name: third-party-notices (license gate)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: native
+      - name: Install cargo-about (pinned)
+        run: |
+          VER=0.9.1
+          curl -sL "https://github.com/EmbarkStudios/cargo-about/releases/download/${VER}/cargo-about-${VER}-x86_64-unknown-linux-musl.tar.gz" | tar xz -C /tmp
+          find /tmp -name cargo-about -type f -executable | head -1 | xargs -I{} sudo mv {} /usr/local/bin/cargo-about
+          cargo-about --version
+      # Fails here if a dependency's license is not in `accepted` (native/about.toml).
+      - name: Regenerate THIRD-PARTY-NOTICES.md
+        run: cargo about generate --manifest-path native/Cargo.toml native/about.hbs -o THIRD-PARTY-NOTICES.md
+      # Fails here if the committed notice does not match what was just regenerated.
+      - name: Verify committed notice is up to date
+        run: |
+          if ! git diff --quiet -- THIRD-PARTY-NOTICES.md; then
+            echo "::error::THIRD-PARTY-NOTICES.md is stale. Regenerate with the command in native/about.toml and commit the result."
+            git diff --stat -- THIRD-PARTY-NOTICES.md
+            exit 1
+          fi
+          echo "THIRD-PARTY-NOTICES.md is up to date."
+
   # ── Gate M1 (P-V, SC-006): prueba de carga de concurrencia ────────────────────────────────
   # Nightly (schedule) + manual (workflow_dispatch): NO corre en PR (no lo bloquea), pero es
   # BLOQUEANTE para el cierre de M1 — el nightly debe estar verde. El harness sale con código ≠ 0

.markdownlintignore

@@ -0,0 +1,3 @@
+# Generated file — verbatim third-party license texts, not authored Markdown.
+# Regenerated and gated by the `third-party-notices` CI job (see native/about.toml).
+THIRD-PARTY-NOTICES.md

CHANGELOG.md

@@ -0,0 +1,49 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Because a document's version identity is the `SHA-256` of its deterministic export, an engine
+encoding change is **breaking** (it invalidates the citability of prior versions) and bumps the
+major.
+
+## [Unreleased]
+
+First release candidate. Everything below is built and verified in CI, pending the operator-gated
+publish to NuGet.org.
+
+### Added
+
+- **Core document & engine (`Weft.Core`).** A CRDT engine abstraction (`ICrdtEngine` / `ICrdtDoc`)
+  over the Rust `yrs` core via an in-house C-ABI shim, with a deterministic native resource
+  lifecycle (`SafeHandle`, explicit disposal, no GC touching native memory) and native panics
+  translated to typed `WeftException`s.
+- **Content-addressed versioning (`Weft.Versioning`).** Publish immutable versions identified by
+  the `SHA-256` of the deterministic export; content-addressed blob store (in-memory, filesystem);
+  word-level LCS text diff; branch/merge with automatic convergence; compaction that preserves all
+  published versions. Engine-agnostic (no dependency on a concrete engine).
+- **Concurrency & lifecycle at scale.** A document broker serializing all access per document
+  (actor/channel, single-reader), with registration, reuse, and inactivity eviction.
+- **Sync relay server (`Weft.Server`).** A WebSocket relay speaking the standard Yjs `y-sync`
+  protocol — existing editor clients (Tiptap + `y-prosemirror`) connect without adaptation.
+  Ephemeral awareness/presence; incremental reconnect via state vectors; a pluggable authorization
+  extension point (`IWeftAuthorizer`); pluggable persistence adapters (in-memory, filesystem,
+  EF Core relational, Redis) validated by a shared contract suite; persist-before-broadcast
+  durability by default, with directory-fsync.
+- **Replaceable engine (`Weft.Loro`).** A Loro adapter implementing the engine abstraction and its
+  optional native versioning surface (`INativeVersioning`), kept compilable and exercised in CI as
+  a continuous portability proof. Cross-engine deterministic seeding (`IDeterministicSeeding`).
+- **Distribution.** NuGet packaging with native binaries for `linux-x64`, `linux-arm64`, `win-x64`,
+  and `osx-arm64`, resolved automatically per platform; a release pipeline (symbols + SourceLink).
+- **Quality gates in CI.** Multi-platform build/tests; ASan/LSan memory verification; `cargo-fuzz`
+  fuzzing of the native boundary and convergence; an encoding-determinism gate cross-checked against
+  the Yjs JS implementation.
+- **Samples & docs.** `Weft.Sample.Versioning`, `Weft.Sample.Server`, and a `tiptap-client`
+  (real editor + headless wire-compat check); architecture doc, per-package API overview, quickstart,
+  and governance/contribution guides.
+
+[Unreleased]: https://github.com/StrangeDaysTech/weft/commits/main

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
+and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the
+  experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior
+and will take appropriate and fair corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits,
+code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and
+will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community
+leaders responsible for enforcement at [Strange Days Tech](https://strangedays.tech/en). All
+complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any
+incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for
+any action they deem in violation of this Code of Conduct:
+
+1. **Correction** — Community Impact: use of inappropriate language or other behavior deemed
+   unprofessional or unwelcome. Consequence: a private, written warning, providing clarity around
+   the nature of the violation and an explanation of why the behavior was inappropriate.
+2. **Warning** — Community Impact: a violation through a single incident or series of actions.
+   Consequence: a warning with consequences for continued behavior.
+3. **Temporary Ban** — Community Impact: a serious violation of community standards. Consequence: a
+   temporary ban from any sort of interaction or public communication with the community.
+4. **Permanent Ban** — Community Impact: demonstrating a pattern of violation of community
+   standards. Consequence: a permanent ban from any sort of public interaction within the
+   community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).

CONTRIBUTING.md

@@ -1,82 +1,82 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# Contribuir a Weft
+# Contributing to Weft
 
-Gracias por tu interés. Weft es una librería .NET (Apache-2.0) de colaboración CRDT en tiempo real y
-versionado content-addressed sobre el core Rust `yrs`, vía un shim C-ABI propio.
+Thanks for your interest. Weft is a .NET library (Apache-2.0) for real-time CRDT collaboration and
+content-addressed versioning over the Rust `yrs` core, via an in-house C-ABI shim.
 
 ## CLA
 
-Toda contribución requiere firmar el **CLA** (Contributor License Agreement) — un bot lo pide
-automáticamente en tu primer PR. Ver [`CLA.md`](./CLA.md).
+Every contribution requires signing the **CLA** (Contributor License Agreement) — a bot requests it
+automatically on your first PR. See [`CLA.md`](./CLA.md).
 
 ## Toolchain
 
 - **.NET SDK 10** (`net10.0`, C# 13).
-- **Rust stable** (fijado en `native/rust-toolchain.toml`); `nightly` solo para ASan/LSan (lo instala CI).
-- Para cross-compilar los binarios nativos localmente (RIDs de Linux): `cargo-zigbuild` + `zig` 0.15.x.
-- Opcional: **Node.js** para el gate de determinismo cross-implementación (`tests/determinism-yjs/`) y el
-  cliente de ejemplo Tiptap.
+- **Rust stable** (pinned in `native/rust-toolchain.toml`); `nightly` only for ASan/LSan (CI installs it).
+- To cross-compile the native binaries locally (Linux RIDs): `cargo-zigbuild` + `zig` 0.15.x.
+- Optional: **Node.js** for the cross-implementation determinism gate (`tests/determinism-yjs/`) and the
+  Tiptap sample client.
 
-## Construir y probar
+## Build and test
 
 ```bash
-# Shim nativo (con test-hooks para la suite de panic-safety, SC-009)
+# Native shim (with test-hooks for the panic-safety suite, SC-009)
 cd native && cargo build --release --features test-hooks && cargo test --features test-hooks && cd ..
 
-# Solución .NET completa
+# Full .NET solution
 dotnet build Weft.sln -c Release
-dotnet test  Weft.sln -c Release        # el test de Redis se salta sin WEFT_TEST_REDIS (Valkey/Redis local)
+dotnet test  Weft.sln -c Release        # the Redis test is skipped without WEFT_TEST_REDIS (local Valkey/Redis)
 ```
 
-> **No empaquetes (`dotnet pack`) desde un árbol compilado con `--features test-hooks`.** El pack lee
-> el cdylib de `native/target/<triple>/release/`; si lo construiste con la feature (p. ej. tras
-> `cargo build --release --target <triple> --features test-hooks`), el `.nupkg` incluiría el símbolo
-> `weft_test_panic`/`weft_loro_test_panic`. El gate SC-009 que verifica su ausencia solo corre en el
-> pipeline de `release.yml`, **no** en un pack local. Para publicar, compila el nativo **sin** la
-> feature (FU-019).
-
-## Gates (constitución)
-
-La constitución del proyecto (`.specify/memory/constitution.md`) fija 6 principios **vinculantes**, cada uno
-con su gate de CI. Un PR no se mergea sin ellos en verde:
-
-| Principio | Gate |
-|---|---|
-| **P-I** FFI segura | ningún panic cruza la frontera C (`catch_unwind` en cada entrada) |
-| **P-II** Memoria verificada | ASan/LSan sobre los tests Rust de ambos shims — 0 fugas / 0 double-free |
-| **P-III** Determinismo | encoding reproducible cross-RID + paridad byte-idéntica cross-impl vs Yjs (**bloqueante** desde CHARTER-09) |
-| **P-IV** Motor reemplazable | la suite de versionado corre idéntica sobre `yrs` **y** Loro (dual-engine) |
-| **P-V** Concurrencia por doc | acceso a `ICrdtDoc` serializado; el broker usa actor/canal single-reader |
-| **P-VI** Portabilidad por RID | *pack-smoke* del paquete en cada RID soportado — "soportado" = ejercitado |
-
-Reglas duras al escribir código: buffers del shim liberados solo con `weft_buf_free` (el GC jamás toca memoria
-nativa); nunca `skip_gc`; `Weft.Versioning` no referencia tipos de `yrs`/Loro (solo las abstracciones); API
-pública con índices `int` validados y errores nativos → jerarquía `WeftException`.
-
-## Protocolo de bump del motor (yrs / Loro) — research R16
-
-Las versiones de los motores están **pinneadas exactas** (`yrs = "=0.27.2"`, `loro = "=1.13.6"`) con
-`Cargo.lock` versionado — los nombres y firmas de `yrs` cambian entre minors, y el gate de determinismo
-(P-III) exige reproducibilidad. Para subir un motor:
-
-1. **Rama dedicada**; actualizar el pin exacto en `native/<crate>/Cargo.toml` + `Cargo.lock`.
-2. **Ajustar el shim** (`native/<crate>/src/lib.rs`) a los cambios de API del motor. El shim aísla el bump: la
-   **C-ABI propia y el C# no cambian** (esa es su razón de ser).
-3. **Correr los gates completos**: sanitizers (P-II), determinismo cross-RID **y cross-implementación**
-   (P-III — un bump puede cambiar el encoding y romper la citabilidad de versiones previas), convergencia y
+> **Do not pack (`dotnet pack`) from a tree built with `--features test-hooks`.** The pack reads the
+> cdylib from `native/target/<triple>/release/`; if you built it with the feature (e.g. after
+> `cargo build --release --target <triple> --features test-hooks`), the `.nupkg` would include the
+> `weft_test_panic`/`weft_loro_test_panic` symbol. The SC-009 gate that verifies its absence only runs
+> in the `release.yml` pipeline, **not** in a local pack. To publish, build the native binary
+> **without** the feature (FU-019).
+
+## Gates (constitution)
+
+The project constitution (`.specify/memory/constitution.md`) fixes 6 **binding** principles, each with
+its CI gate. A PR is not merged without them green:
+
+| Principle | Gate |
+| --- | --- |
+| **P-I** Safe FFI | no panic crosses the C boundary (`catch_unwind` at every entry point) |
+| **P-II** Verified memory | ASan/LSan over the Rust tests of both shims — 0 leaks / 0 double-free |
+| **P-III** Determinism | reproducible encoding cross-RID + byte-identical cross-impl parity vs Yjs (**blocking** since CHARTER-09) |
+| **P-IV** Replaceable engine | the versioning suite runs identically over `yrs` **and** Loro (dual-engine) |
+| **P-V** Per-doc concurrency | serialized access to `ICrdtDoc`; the broker uses a single-reader actor/channel |
+| **P-VI** Portability by RID | *pack-smoke* of the package on every supported RID — "supported" = exercised |
+
+Hard rules when writing code: shim buffers freed only with `weft_buf_free` (the GC never touches native
+memory); never `skip_gc`; `Weft.Versioning` does not reference `yrs`/Loro types (only the abstractions);
+public API with validated `int` indices and native errors → `WeftException` hierarchy.
+
+## Engine bump protocol (yrs / Loro) — research R16
+
+Engine versions are **pinned exactly** (`yrs = "=0.27.2"`, `loro = "=1.13.6"`) with a versioned
+`Cargo.lock` — `yrs`'s names and signatures change between minors, and the determinism gate (P-III)
+requires reproducibility. To bump an engine:
+
+1. **Dedicated branch**; update the exact pin in `native/<crate>/Cargo.toml` + `Cargo.lock`.
+2. **Adjust the shim** (`native/<crate>/src/lib.rs`) to the engine's API changes. The shim isolates the
+   bump: the **in-house C-ABI and the C# do not change** (that's its whole point).
+3. **Run the full gates**: sanitizers (P-II), determinism cross-RID **and cross-implementation** (P-III
+   — a bump can change the encoding and break the citability of prior versions), convergence, and
    dual-engine (P-IV).
-4. **Merge solo en verde.** Un cambio de encoding es *breaking* para el content-addressing → se trata como
-   tal en el versionado SemVer del paquete.
+4. **Merge only when green.** An encoding change is *breaking* for content-addressing → it's treated as
+   such in the package's SemVer versioning.
 
-## Flujo de trabajo
+## Workflow
 
-Spec-driven con [GitHub Spec Kit](https://github.com/github/spec-kit) (spec → plan → tasks → implement) y
-gobernanza documental con [StrayMark](https://github.com/StrangeDaysTech/straymark) (Charters + AILOG/AIDEC).
-Ver [`GOVERNANCE.md`](./GOVERNANCE.md). Las decisiones ✅ CERRADO del brief (`weft-design-brief.md`) no se
-re-litigan.
+Spec-driven with [GitHub Spec Kit](https://github.com/github/spec-kit) (spec → plan → tasks → implement)
+and documentation governance with [StrayMark](https://github.com/StrangeDaysTech/straymark) (Charters +
+AILOG/AIDEC). See [`GOVERNANCE.md`](./GOVERNANCE.md). The ✅ CLOSED decisions of the brief
+(`weft-design-brief.md`) are not re-litigated.
 
-## Reportar bugs / proponer cambios
+## Reporting bugs / proposing changes
 
-Abre un issue con repro mínimo. Para cambios sustantivos, comenta el diseño en un issue antes del PR — los
-cambios de contrato (FFI, `IDocumentStore`, protocolo de sync) requieren acuerdo previo.
+Open an issue with a minimal repro. For substantive changes, discuss the design in an issue before the
+PR — contract changes (FFI, `IDocumentStore`, sync protocol) require prior agreement.