[chrisjsewell]

Summary

A new derive kind, fingerprint, gives a field the SHA-256 of the whole need, for change detection:

[needs.fields.fp]
schema = { type = "string" }
derive = { kind = "fingerprint" }

.. spec:: Reviewed against REQ_1
   :id: SPEC_1
   :links: REQ_1[fp == "<REQ_1's fingerprint when it was reviewed>"]

The condition holds while REQ_1 is unchanged, and reports needs.link_condition_failed once it changes;
writing the new value accepts the change. A prefix is enough: REQ_1[fp.startswith('3f9a1c2b7d4e')].

Design

• The set: id, type, title, status, tags, content (a need nested in another's body is part of the
  parent's content), every field the project declares (needs_fields, needs_extra_options) and every link type,
  links included, none derived. Never: derived fields and link types (hashes, other fingerprints), back links,
  parent_needs, parts, constraints, location, presentation, bookkeeping, or fields an extension or service
  registers (unless the project declares that name itself).
• The entry rule: a name enters only where its value differs from the field's default, compared as JSON text
  (a literal default, else null when nullable, else [] for a link type or tags, else — a non-nullable field
  without a literal default — it always enters; id/type/title always; a number field's value and default as
  floats, so default = 1 is 1.0). A value written equal to its default is the same as unset, and -0.0 differs
  from 0.0. Declaring a field or link type moves no fingerprint while the needs leave it unset, if its default is
  a literal or there is none; a [[…]] or variant default, and predicates, give the needs a value, which enters as
  a written one would (adding owner with default = "[[copy('title')]]" moves every need's fingerprint).
• Frozen: no later release changes which names a fingerprint includes, when a name enters, or how the text is
  written: a fingerprint written down stays current until the need, or the configuration of the fields it
  reads, changes.
• The text: one compact JSON object, keys sorted, written as hash writes values; SHA-256, lowercase hex.
• Link conditions dropped (targets kept, deduplicated, in the export's order), so pinning an upstream need's
  fingerprint never moves the pinning need's own.
• exclude: the one optional role, a list of names the fingerprint includes, each once ([] allowed);
  anything else is needs.derive_invalid, as are fields/after on it and exclude on hash.
• Late, like hash: computed from final values (needextend, variants, [[…]]); a non-late reader is
  needs.derive_scope; no rule runs on imported or external needs.

Tests

• Seven cases appended to the derived-field conformance corpus (EXPECTED_CASE_COUNT 36 → 43; only additions, the
  36 existing cases byte-for-byte): fingerprint-whole-need, fingerprint-new-field-keeps-digest,
  fingerprint-exclude-and-empty-values, fingerprint-in-a-link-condition, fingerprint-invalid-shapes,
  fingerprint-late-and-scope, fingerprint-defaults-compared-as-text. Their hexes were computed by an independent
  prototype of the byte format (amended for the float rule of a number field's integer default) before the
  implementation existed, and the implementation reproduces them.
• tests/test_derive_fingerprint.py: every load check with its text and order, the included names, the entry
  rule's edges, registered fields, final values, hidden/nested/imported/external needs, change detection.
• One order test in tests/test_functions_order.py.

ubCode follows in a twin PR, vendoring the corpus.

Changelog

The 9.0.0 "Unreleased" entry for derived fields gains fingerprint in its list of kinds, a sentence on what it
digests (every declared, non-derived field and link type, links among them) and how a link condition uses it, and
the frozen promise.

uv run poe lint and uv run poe typecheck pass.

When squashing, strip the Co-authored-by trailer GitHub proposes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.69%. Comparing base (8ac3974) to head (9997e39).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2204      +/-   ##
==========================================
+ Coverage   93.63%   93.69%   +0.06%     
==========================================
  Files         141      141              
  Lines       21965    22060      +95     
==========================================
+ Hits        20566    20670     +104     
+ Misses       1399     1390       -9     

Flag	Coverage Δ
ai-index	100.00% <ø> (ø)
codelinks	96.22% <ø> (ø)
mounts	94.27% <ø> (ø)
pytests	92.95% <100.00%> (+0.11%)	⬆️
reports	96.23% <ø> (ø)
ub-test-reports	90.94% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.