From d0d79d2f07b29a54ae6629ea660c372dc447119b Mon Sep 17 00:00:00 2001
From: sergeych <real.sergeych@gmail.com>
Date: Tue, 7 Apr 2026 19:53:01 +0300
Subject: [PATCH] docs: add LegacyDigest module documentation

- New docs/LegacyDigest.md: full reference for lyng.legacy_digest,
  covering the sha1() API, input types (String / Buffer), FIPS compliance
  note, and explicit guidance on appropriate vs. inappropriate use.

- docs/ai_stdlib_reference.md: entry in section 5 so AI agents know
  LegacyDigest.sha1() exists and is intentionally named as legacy-only.

- docs/whats_new.md: release-note section alongside Complex, Decimal,
  and Matrix, with a minimal runnable example and cross-link.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/LegacyDigest.md        | 66 +++++++++++++++++++++++++++++++++++++
 docs/ai_stdlib_reference.md |  3 ++
 docs/whats_new.md           | 25 ++++++++++++++
 3 files changed, 94 insertions(+)
 create mode 100644 docs/LegacyDigest.md

diff --git a/docs/LegacyDigest.md b/docs/LegacyDigest.md
new file mode 100644
index 0000000..2c7dc78
--- /dev/null
+++ b/docs/LegacyDigest.md
@@ -0,0 +1,66 @@
+# Legacy Digest Functions (`lyng.legacy_digest`)
+
+> ⚠️ **Security warning:** The functions in this module use cryptographically broken
+> algorithms.  Do **not** use them for passwords, digital signatures, integrity
+> verification against adversarial tampering, or any other security-sensitive
+> purpose.  They exist solely for compatibility with legacy protocols and file
+> formats that require specific hash values.
+
+Import when you need to produce a SHA-1 digest for an existing protocol or format:
+
+```lyng
+import lyng.legacy_digest
+```
+
+## `LegacyDigest` Object
+
+### `sha1(data): String`
+
+Computes the SHA-1 digest of `data` and returns it as a 40-character lowercase
+hex string.
+
+`data` can be:
+
+| Type     | Behaviour                              |
+|----------|----------------------------------------|
+| `String` | Encoded as UTF-8, then hashed          |
+| `Buffer` | Raw bytes hashed directly              |
+| anything | Falls back to `toString()` then UTF-8  |
+
+```lyng
+import lyng.legacy_digest
+
+// String input
+val h = LegacyDigest.sha1("abc")
+assertEquals("a9993e364706816aba3e25717850c26c9cd0d89d", h)
+
+// Empty string
+assertEquals("da39a3ee5e6b4b0d3255bfef95601890afd80709", LegacyDigest.sha1(""))
+```
+
+```lyng
+import lyng.legacy_digest
+import lyng.buffer
+
+// Buffer input (raw bytes)
+val buf = Buffer.decodeHex("616263")   // 0x61 0x62 0x63 = "abc"
+assertEquals("a9993e364706816aba3e25717850c26c9cd0d89d", LegacyDigest.sha1(buf))
+```
+
+## Implementation Notes
+
+- Pure Kotlin/KMP — no native libraries or extra dependencies.
+- Follows FIPS 180-4.
+- The output is always lowercase hex, never uppercase or binary.
+
+## When to Use
+
+Use `lyng.legacy_digest` only when an external system you cannot change requires
+a SHA-1 value, for example:
+
+- old git-style content addresses
+- some OAuth 1.0 / HMAC-SHA1 signature schemes
+- legacy file checksums defined in published specs
+
+For any new design choose a current hash function (SHA-256 or better) once
+Lyng adds a `lyng.digest` module.
diff --git a/docs/ai_stdlib_reference.md b/docs/ai_stdlib_reference.md
index db45c7b..5abf619 100644
--- a/docs/ai_stdlib_reference.md
+++ b/docs/ai_stdlib_reference.md
@@ -75,6 +75,9 @@ Sources: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt`, `lynglib/s
   - `Matrix`, `Vector`, `matrix(rows)`, `vector(values)`, dense linear algebra, inversion, solving, and matrix slicing with `m[row, col]`.
 - `import lyng.buffer`
   - `Buffer`, `MutableBuffer`.
+- `import lyng.legacy_digest`
+  - `LegacyDigest.sha1(data): String` — SHA-1 hex digest; `data` may be `String` (UTF-8) or `Buffer` (raw bytes).
+  - ⚠️ Cryptographically broken. Use only for legacy protocol / file-format compatibility.
 - `import lyng.serialization`
   - `Lynon` serialization utilities.
 - `import lyng.time`
diff --git a/docs/whats_new.md b/docs/whats_new.md
index 01796a8..8c72d5c 100644
--- a/docs/whats_new.md
+++ b/docs/whats_new.md
@@ -164,6 +164,31 @@ println(z.exp())
 
 See [Complex](Complex.md).
 
+### Legacy Digest Module (`lyng.legacy_digest`)
+
+For situations where an external protocol or file format requires a SHA-1 value,
+Lyng now ships a `lyng.legacy_digest` module backed by a pure Kotlin/KMP
+implementation with no extra dependencies.
+
+> ⚠️ SHA-1 is cryptographically broken.  Use only for legacy-compatibility work.
+
+```lyng
+import lyng.legacy_digest
+
+val hex = LegacyDigest.sha1("abc")
+// → "a9993e364706816aba3e25717850c26c9cd0d89d"
+
+// Also accepts raw bytes:
+import lyng.buffer
+val buf = Buffer.decodeHex("616263")
+assertEquals(hex, LegacyDigest.sha1(buf))
+```
+
+The name `LegacyDigest` is intentional: it signals that these algorithms belong
+to a compatibility layer, not to a current security toolkit.
+
+See [LegacyDigest](LegacyDigest.md).
+
 ### Binary Operator Interop Registry
 Lyng now provides a general mechanism for mixed binary operators through `lyng.operators`.