dsh-image-integrity 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[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).
+
+## [Unreleased]
+
+### Fixed
+
+- Enforce `maxPixels` from the IHDR **before** inflating IDAT, and pass the
+  expected decompressed size as `inflateSync.maxOutputLength`; a small PNG with
+  huge dimensions can no longer allocate an arbitrarily large buffer. The
+  exported decoder also defaults to the same 4,000,000-pixel cap.
+- Validate per-call thresholds (`blockSize` 2–256, `maxShiftBits`
+  0–blockSize², finite non-negative `minVariance`, NCC 0–1) so `blockSize: 0`
+  cannot loop forever and NaN/out-of-range options cannot silently disable
+  detection.
+- `image_report` validates the analysis/matches shapes and returns
+  `INVALID_INPUT` instead of dereferencing undefined fields.
+- Report the effective block size in `blocks` when the image is smaller than
+  the requested block, matching `blockSize` and `considered`.
+
+### Changed
+
+- Precompute mirrored bit patterns once per block and stop Hamming counting
+  once the tolerance is exceeded, removing per-pair mirror allocations from
+  the O(n²) comparison loop.
+- Test count is now 22; README/CHANGELOG list the new failure branches.
+
+## [0.1.0] - 2026-11-08
+
+First release: block-level image reuse detection.
+
+### Added
+
+- `image_check`: duplicated and mirrored 16×16 textured blocks inside one PNG,
+  with Hamming/NCC scores.
+- `image_compare`: shared duplicated/mirrored blocks between two PNGs; a
+  dimension mismatch is reported, never resized.
+- `image_report`: Markdown + SARIF 2.1.0.
+- Zero-dependency PNG decoder (8-bit, non-interlaced, grey/RGB/RGBA) with
+  bounds-checked chunks, plus a greyscale encoder used by tests.
+- False-positive controls: flat blocks and blocks that are close to a fitted
+  plane are ignored, so smooth gradients do not read as duplicates.
+- REP v1 integration: image bytes become immutable snapshots with figure
+  anchors (ordinal included), one check per matched region, and a valid record.
+- 18 tests.
+
+### Notes
+
+- Finds reused pixels, not manipulation intent; repeated controls are normal.
+- JPEG/WebP/TIFF are not decoded in v0.1 and are rejected explicitly.
+- The 100-pair benchmark is not yet frozen; no benchmark numbers are claimed.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README-zh.md

@@ -0,0 +1,98 @@
+# dsh-image-integrity
+
+**这张子图是不是被复用了 —— 原地重复，还是从另一张图镜像粘贴过来？**
+
+*零依赖 PNG 解码、带 NCC 确认的均值阈值块指纹、重复/镜像区域报告、REP 证据与 SARIF。它找的是被复用的像素，而不是操纵意图。*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-brightgreen.svg)]()
+
+[English](README.md) · 简体中文
+
+---
+
+## 它做什么
+
+- **`image_check`** —— 在单张图片内找出出现两次（或以镜像形式出现）的纹理块。
+- **`image_compare`** —— 找出两张图片之间共有的块，包括镜像副本。
+- **`image_report`** —— Markdown + SARIF 2.1.0，每个匹配区域一条 warning，附坐标、汉明距离与 NCC。
+
+工作原理：解码 PNG → 亮度 → 16×16 块 → 均值阈值位模式（可抵抗亮度偏移）+ 零均值 NCC 确认。平坦**或接近拟合平面**的块会被跳过，因此平滑渐变不会被报成“重复”。
+
+## 它不做什么
+
+- **不支持 JPEG。** 只解码 8 位非隔行 PNG（灰度/RGB/RGBA）。JPEG/16 位/隔行 PNG 会以明确的错误码拒绝 —— 不会静默返回垃圾结果。
+- **不做对齐。** 图片尺寸必须完全相同；尺寸不一致会报告，绝不缩放。
+- **不抗模糊/压缩。** 经 JPEG 重压缩、缩放、旋转或拼接混合后，通常就检测不出来了。
+- **不指控学术不端。** 重复的对照图、比例尺、图标与背景纹理都是合法的共享块。报告会说明这一点。
+- **没有 GUI，也不上传。** 只处理本地字节。
+
+## 工具
+
+### `image_check`
+
+`{ path, persist?, blockSize?, maxShiftBits?, minVariance?, nccThreshold? }` → `{ ok, analysis, evidenceId?, recordPath? }`。
+
+### `image_compare`
+
+`{ pathA, pathB, persist?, ...thresholds }` → `{ ok, analysis, evidenceId?, recordPath? }`。
+
+### `image_report`
+
+`{ analysis, imageId? }` → `{ ok, markdown, sarif }`。
+
+### 错误码
+
+`INVALID_INPUT` · `NOT_FOUND` · `PATH_ESCAPE` · `NOT_A_FILE` · `TOO_LARGE` · `UNSUPPORTED_IMAGE` · `STORE_ERROR`
+
+## 兼容性与安装
+
+| | |
+|---|---|
+| DeepSeek Harness | **`dsh-v0.2.1-rc.5`**（2026-11-08 实测）；peer `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0` |
+| Node | `^22.19.0 \|\| >=24.9.0`（实测 `24.22.1`），仅 ESM |
+| Peer 依赖 | `@perrylink/dsh-research-core ^0.1.0`、`@deepseek-ai/cordis ^4.0.5-alpha.1`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/schemastery ^3.18.5-alpha.1` |
+| 运行时依赖 | **零**（PNG 解码通过 `node:zlib`） |
+
+```sh
+dsh plugin --profile <name> add @perrylink/dsh-research-core dsh-image-integrity
+dsh --profile <name> --dump-config | grep dsh-image-integrity
+```
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `enabled` | `true` | `false` 时不挂载任何内容 |
+| `root` | `.image-integrity` | 存储/记录的根目录 |
+| `workspaceRoot` | `process.cwd()` | 路径必须解析到该目录内 |
+| `maxBytes` | `20971520` | 文件大小上限（超限即失败，绝不截断） |
+| `maxPixels` | `4000000` | 解码后的像素数上限 |
+| `persist` | `true` | 将图片存为 REP 证据并写入记录 |
+| `blockSize` / `maxShiftBits` | `16` / `6` | 块边长（2–256）；位容差（0–blockSize²） |
+| `minVariance` / `nccThreshold` | `6` / `0.97` | 纹理下限；NCC 确认阈值 |
+
+## 安全边界
+
+- 对图片只读；只在 `root` 下写入。
+- `realpath` 路径包含校验会拒绝符号链接逃逸。
+- 对字节数和像素数设硬上限；像素上限在解压**之前**就根据 IHDR 检查，`inflateSync` 也按预期输出大小加以限制。失败会显式报错。
+- 每次调用的阈值都会校验（`blockSize` 2–256，`maxShiftBits` 0–blockSize²，NCC 0–1）；非法阈值返回 `INVALID_INPUT`，不会崩溃。
+- PNG 解析器对每个 chunk 做边界检查；不支持的格式直接拒绝，不做猜测。
+
+## 评测
+
+**22 个测试**：PNG 往返、非 PNG / 16 位 / 截断文件拒绝、解压前依据 IHDR 拒绝超像素上限（配置值与默认值）、汉明距离与 NCC 基础函数、重复块检测、水平镜像检测、平坦图与渐变图的误报控制、小图的有效块大小、成对匹配、尺寸不一致时拒绝、runtime（合法 REP 记录、每次比较生成两份快照、路径遍历/JPEG/字节与像素超限拒绝、非法阈值拒绝）、tools（schema、check→report、compare、格式错误的报告、失败分支）、包契约。
+
+**基准测试状态：尚未声称。** 计划中的 `dsh-research-bench` 数据集是 100 对合成 PNG（重复 / 镜像 / 无关 / 困难负样本）。在该数据集冻结并评分之前，上述单元 fixture 是唯一的证据，README 也如实说明这一点。
+
+## 已知限制（v0.1）
+
+- 仅支持 PNG；不支持 JPEG/WebP/TIFF。
+- 不抗缩放/旋转/重压缩。
+- 块网格与坐标轴对齐；偏移几个像素的重复区域可能被漏掉。
+- 不分析颜色通道或元数据（EXIF）。
+
+## 许可
+
+Apache-2.0。运行时不含第三方代码。

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# dsh-image-integrity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Is that panel reused — duplicated in place, or pasted mirrored from another figure?**
+
+*Zero-dependency PNG decoding, mean-threshold block fingerprints with NCC confirmation, duplicate/mirror region reports, REP evidence and SARIF. It finds reused pixels, not manipulation intent.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-brightgreen.svg)]()
+
+English · [简体中文](README-zh.md)
+
+---
+
+## What it does
+
+- **`image_check`** — finds a textured block that appears twice (or mirrored) inside one image.
+- **`image_compare`** — finds blocks shared between two images, including mirrored copies.
+- **`image_report`** — Markdown + SARIF 2.1.0, one warning per matched region with coordinates, Hamming distance and NCC.
+
+How it works: decode PNG → luma → 16×16 blocks → mean-threshold bit pattern (robust to brightness offsets) + zero-mean NCC confirmation. Blocks that are flat **or close to a fitted plane** are skipped, so a smooth gradient is not reported as "duplicated".
+
+## What it does not do
+
+- **No JPEG.** Only 8-bit non-interlaced PNG (grey/RGB/RGBA) is decoded. JPEG/16-bit/interlaced are rejected with a clear code — no silent garbage.
+- **No alignment.** Images must have identical dimensions; a mismatch is reported, never resized.
+- **No blur/compression robustness.** JPEG recompression, scaling, rotation or splice blending will usually defeat it.
+- **No misconduct claim.** Repeated controls, scale bars, icons and background texture are legitimate shared blocks. The report says so.
+- **No GUI, no upload.** Local bytes only.
+
+## Tools
+
+### `image_check`
+
+`{ path, persist?, blockSize?, maxShiftBits?, minVariance?, nccThreshold? }` → `{ ok, analysis, evidenceId?, recordPath? }`.
+
+### `image_compare`
+
+`{ pathA, pathB, persist?, ...thresholds }` → `{ ok, analysis, evidenceId?, recordPath? }`.
+
+### `image_report`
+
+`{ analysis, imageId? }` → `{ ok, markdown, sarif }`.
+
+### Error codes
+
+`INVALID_INPUT` · `NOT_FOUND` · `PATH_ESCAPE` · `NOT_A_FILE` · `TOO_LARGE` · `UNSUPPORTED_IMAGE` · `STORE_ERROR`
+
+## Compatibility & install
+
+| | |
+|---|---|
+| DeepSeek Harness | **`dsh-v0.2.1-rc.5`** (verified 2026-11-08); peer `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0` |
+| Node | `^22.19.0 \|\| >=24.9.0` (tested `24.22.1`), ESM only |
+| Peers | `@perrylink/dsh-research-core ^0.1.0`, `@deepseek-ai/cordis ^4.0.5-alpha.1`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/schemastery ^3.18.5-alpha.1` |
+| Runtime dependencies | **zero** (PNG via `node:zlib`) |
+
+```sh
+dsh plugin --profile <name> add @perrylink/dsh-research-core dsh-image-integrity
+dsh --profile <name> --dump-config | grep dsh-image-integrity
+```
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | `false` mounts nothing |
+| `root` | `.image-integrity` | store/record root |
+| `workspaceRoot` | `process.cwd()` | paths must resolve inside it |
+| `maxBytes` | `20971520` | file cap (fails, never truncates) |
+| `maxPixels` | `4000000` | decoded pixel cap |
+| `persist` | `true` | store images as REP evidence + record |
+| `blockSize` / `maxShiftBits` | `16` / `6` | block side (2–256); bit tolerance (0–blockSize²) |
+| `minVariance` / `nccThreshold` | `6` / `0.97` | texture floor; NCC confirmation |
+
+## Security boundaries
+
+- Read-only on images; writes only under `root`.
+- `realpath` containment rejects symlink escapes.
+- Hard caps on bytes and pixels; the pixel cap is checked from the IHDR
+  **before** inflation, and `inflateSync` is bounded by the expected output
+  size. Failures are loud.
+- Per-call thresholds are validated (`blockSize` 2–256, `maxShiftBits`
+  0–blockSize², NCC 0–1); an invalid threshold is `INVALID_INPUT`, not a crash.
+- PNG parser bounds-checks every chunk; unsupported formats are rejected, not guessed.
+
+## Evaluation
+
+**22 tests**: PNG round-trip, non-PNG / 16-bit / truncated rejection, pixel-cap rejection from the IHDR before inflation (configured and default), Hamming and NCC primitives, duplicate block detection, horizontal mirror detection, flat-image and gradient false-positive controls, small-image effective block size, pair matching, dimension-mismatch refusal, runtime (valid REP record, two snapshots per comparison, traversal/JPEG/byte-and-pixel oversize rejection, invalid threshold rejection), tools (schemas, check→report, compare, malformed report, failure branch), package contract.
+
+**Benchmark status: not yet claimed.** The planned `dsh-research-bench` set is 100 synthetic PNG pairs (duplicate / mirrored / unrelated / hard negative). Until that set is frozen and scored, the unit fixtures above are the only evidence, and the README says so.
+
+## Known limitations (v0.1)
+
+- PNG-only; no JPEG/WebP/TIFF.
+- No scaling/rotation/recompression robustness.
+- Block grid is axis-aligned; a duplicated region shifted by a few pixels can be missed.
+- No colour-channel or metadata (EXIF) analysis.
+
+## License
+
+Apache-2.0. No third-party runtime code.

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# dsh-image-integrity bundle patch: mount the image integrity tools.
+#
+# Every key below is a Config field (Schemastery schema); invalid values fail the
+# profile load loudly. Analysis is local; nothing is uploaded.
+- insert:
+    - id: dsh-image-integrity
+      name: dsh-image-integrity
+      config:
+        enabled: true
+        root: .image-integrity
+        # 20 MiB file cap and 4 MP pixel cap; over-limit fails, never truncated.
+        maxBytes: 20971520
+        maxPixels: 4000000
+        persist: true
+        # Detection defaults (block side, bit tolerance of 256, flat-block floor,
+        # NCC confirmation threshold).
+        blockSize: 16
+        maxShiftBits: 6
+        minVariance: 6
+        nccThreshold: 0.97

package/lib/analyze.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Block-level duplication and mirroring detection.
+ *
+ * Each block is reduced to a mean-threshold bit pattern (robust to additive
+ * brightness changes) plus its zero-mean normalised correlation (NCC) for
+ * confirmation. Blocks with too little variance (flat backgrounds) are skipped,
+ * which is the main defence against false positives on uniform areas.
+ *
+ * This detects **reused pixels**, not manipulation intent: a duplicated control
+ * panel is normal, a duplicated experimental panel usually is not. The report
+ * always says which regions matched and at what score.
+ *
+ * @module dsh-image-integrity/analyze
+ */
+import type { RgbaImage } from './png.ts';
+/** Options shared by single-image and pair analysis. */
+export interface ImageOptions {
+    /** Block side in pixels (default 16). */
+    readonly blockSize?: number;
+    /** Maximum Hamming distance on the block bit pattern (default 6 of 256). */
+    readonly maxShiftBits?: number;
+    /** Minimum block variance; flatter blocks are ignored (default 6). */
+    readonly minVariance?: number;
+    /** NCC confirmation threshold (default 0.97). */
+    readonly nccThreshold?: number;
+}
+/** A matched region. */
+export interface RegionMatch {
+    readonly kind: 'duplicate' | 'horizontal-flip' | 'vertical-flip';
+    readonly a: {
+        readonly x: number;
+        readonly y: number;
+        readonly block: number;
+    };
+    readonly b: {
+        readonly x: number;
+        readonly y: number;
+        readonly block: number;
+    };
+    readonly hamming: number;
+    readonly ncc: number;
+}
+/** Result of analysing one image. */
+export interface ImageAnalysis {
+    readonly width: number;
+    readonly height: number;
+    readonly blockSize: number;
+    readonly blocks: number;
+    readonly considered: number;
+    readonly matches: readonly RegionMatch[];
+    readonly duplicatePairs: number;
+    readonly flippedPairs: number;
+    readonly warnings: readonly string[];
+}
+/** Result of comparing two images. */
+export interface PairAnalysis {
+    readonly a: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly b: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly matches: readonly RegionMatch[];
+    readonly duplicatePairs: number;
+    readonly flippedPairs: number;
+    readonly warnings: readonly string[];
+}
+/** Convert to luma. */
+export declare function toGray(image: RgbaImage): Float64Array;
+/**
+ * Hamming distance between two bit arrays.
+ * @param left - first bits.
+ * @param right - second bits.
+ * @param limit - stop early once the distance exceeds this (default: exact).
+ * @returns the exact distance, or a value greater than `limit`.
+ */
+export declare function hamming(left: Uint8Array, right: Uint8Array, limit?: number): number;
+/** Zero-mean NCC of two equal-length vectors. */
+export declare function ncc(left: Float64Array, right: Float64Array): number;
+/**
+ * Fill defaults and validate thresholds.
+ *
+ * Validation lives here (not only in the runtime) because `analyzeImage` and
+ * `compareImages` are exported: `blockSize: 0` would otherwise divide by zero
+ * and loop forever, and a negative/NaN variance or out-of-range NCC threshold
+ * would silently change every result.
+ * @param options - caller overrides.
+ * @returns fully resolved options.
+ */
+export declare function resolveImageOptions(options?: ImageOptions): Required<ImageOptions>;
+/**
+ * Analyse one image for reused blocks and mirrored copies.
+ * @param image - decoded image.
+ * @param options - detection thresholds.
+ * @returns matches and counts.
+ */
+export declare function analyzeImage(image: RgbaImage, options?: ImageOptions): ImageAnalysis;
+/**
+ * Compare two images block by block.
+ * @param left - first image.
+ * @param right - second image.
+ * @param options - detection thresholds.
+ * @returns cross-image matches and counts.
+ */
+export declare function compareImages(left: RgbaImage, right: RgbaImage, options?: ImageOptions): PairAnalysis;
+//# sourceMappingURL=analyze.d.ts.map

package/lib/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"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"}