@filipebraida/adonis-function-points 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,161 @@ release moves the number for unchanged code, the rule set version moves with it
 otherwise the difference would measure the tool's change rather than the work, and
 that difference becomes an invoice.
 
+## 0.6.0
+
+**Rule set `afp@1.5.0`.** Six rules change what a number is made of, all of them found
+by counting real applications function by function against what a certified counter
+would write down — and every one was frozen in a fixture with a hand-written reference
+**before** the code. A 0.5.0 baseline has to be recounted; on the three applications
+this release was reviewed against the totals move −18, −8 and −37 FP, and the whole
+of it is EOs losing DETs they never showed and one data function that was four.
+
+### Counting
+
+- **An output's DETs are what leaves the boundary, not every column read.** A
+  transformer decides the output of the store it is FOR (`BaseTransformer<X>`, and the
+  resources of the transformers nested in it): the keys the reached method returns, a
+  nested transformer's keys once, `this.pick([...])` by name, `xs.map(...)` as a
+  repeating group. For every other store touched, what leaves is what the code shows:
+  rows whole (every column), the columns a `.select()` names, or **one derived scalar**
+  for `.count()` / `.exists()`. A relation preloaded through a covered store and read
+  no other way is covered too — it was loaded for the transformer. A spread the walker
+  cannot read counts 1 DET as a floor and is reported, like an open input object.
+  Before, a detail page through three transformers came out at 67 DET; a dashboard of
+  eight counters at 84.
+- **A system timestamp is not a DET.** `autoCreate` / `autoUpdate` say the framework
+  stamps the column; the user neither supplies nor recognises it — the ground the key
+  was already excluded on. Excluded on the data function, on every output, and on a
+  transformer that re-emits it. A `dateTime` the user sets still counts. AFP §7.2 on
+  its letter would count both; the departure is now consistent, and counting-decisions
+  §6 says so.
+- **A column declared `serializeAs: null` never leaves.** Lucid does not serialise it,
+  so it is not an output DET however the store leaves. It stays a DET of the data
+  function. Found as `User.password` on an activity log's output.
+- **A detail the user only sees inside its master is a RET, not a data function.** A
+  `hasMany` / `hasOne` child that no application code addresses directly — only
+  `related()` / `preload()` from the parent — folds into the parent: one ILF with N RET,
+  the child's link to the parent excluded from the DETs, one FTR for a transaction
+  touching both. A child with a query of its own stays its own file (the Vazquez
+  benchmark depends on it); a child hanging off two parents stays apart and the report
+  says why. Cascade delete was measured and rejected as the signal: on one application
+  11 of 13 cascades pointed at the tenant table. On the three applications the rule
+  folds four stores in all — the `Inpi*` mirror of an external registry becomes **one**
+  EIF with 4 RET, which is what the CPM says.
+- **A data function is identified by its table**, as counting-decisions §5 always said.
+  Keyed by the class, renaming a model billed as a deletion plus an addition.
+- **A token table is technical.** `password_reset_tokens`, `auth_access_tokens`,
+  `remember_me_tokens` are the machinery of authentication; `.*tokens?.*` joins the
+  naming list. And the list is now configurable in fact — `boundary.technicalPatterns`
+  replaces it, `DEFAULT_TECHNICAL_PATTERNS` is exported to start from — as §4 and the
+  filter's own comment had claimed since 0.1.0 while `counter.ts` passed nothing.
+
+### Configuration
+
+- **`opaque.<Store.column | validator.field>`** replaces `overrides.<fn>.detFromSchema`
+  and `overrides.<fn>.opaqueReviewed`. A declaration about a DET the analysis cannot read
+  is about the column or the validator field — its ORIGIN — and applies to every
+  function that carries it: the ILF, the transaction that submits it, each screen that
+  shows it. Read from a real configuration, the old shape had the same mapping written
+  twice and a `GET` returning the same column still at 1 DET: the same column worth two
+  numbers in one count. Reviews are matched exactly; matched by bare name, reviewing
+  `Message.schema` reviewed every `schema` column of every store. A column may be keyed
+  by model or by table. The two old keys are gone from the type — an old configuration
+  fails to typecheck — and, because a configuration file is loaded without types,
+  `fp:count` still tells one that carries them that they had no effect.
+  `overrides.<fn>.det` / `.refs` remain per function.
+- **`dataFunctions.grouping: 'usage' | 'none'`** replaces `retStrategy`. `none` is the
+  0.5.0 behaviour — every table its own data function at RET 1 — for comparing with an
+  old count; it is not a preference. `retStrategy` is gone from the type, and `fp:count`
+  says so when an untyped configuration still carries it.
+- **`boundary.technicalPatterns`**, see above.
+
+### New
+
+- **The count names what it cannot decide.** Two transactions of the same type that
+  reach the same stores, emit the same DETs and walk the same bodies below the
+  controller are reported as look-alikes with the FP at stake — the CPM counts
+  identical processing logic once, and `boundary.ignoreEntryPoints` records the
+  decision. An EIF only a seeder writes is reported too: code data the team maintains
+  is not counted, a mirror of another system's data is a legitimate EIF, and the code
+  cannot tell which. Neither moves a number (counting-decisions §11).
+- **`diff.preset: 'sisp'`** prices change by the Roteiro de Métricas de Software do SISP
+  v3.0 (Portaria SGD/MGI nº 3656/2026), §7.3 — inclusão 1,00, alteração × FI 0,63 (the
+  contractor maintains its own work; 0,84 otherwise, via `factors`), exclusão 0,50 —
+  instead of AEP. `fp:diff` prints which preset produced the billable total. Read from
+  the guide's PDF: a first draft of this preset said 0,50 / 0,30 from memory, and v2.0
+  (2012) priced exclusion at 0,40 — a contract binds to a revision, so check yours.
+- **`ignoreCalls({ name, methods | matching })`** builds a "this reaches no data"
+  strategy without the ceremony a real configuration had to carry — a helper to read
+  the method name off a ts-morph node, a `resolve` that returns nothing, one comparison.
+  The strategy is still named, and its volume is still reported.
+- The configuration stub no longer echoes defaults.
+
+### Documented
+
+- counting-decisions §6 now describes what the code does for output DETs, row by row,
+  and records the two refinements the recounts forced; §4 says plainly that only the
+  naming mechanism of the technical filter exists, and why the lookup-structure rule
+  was rejected; §9 gains "Declared by origin, not by function"; §10 is the master-detail
+  rule, with the cascade measurement that rejected the structural signal; §11 is what
+  the count reports because it cannot decide.
+- Five reference fixtures were written before their rules: `transformed_output` (59 FP,
+  eight output shapes), `system_timestamps` (18), `mestre_detalhe` (41; 51 with
+  grouping off), and additions to `edges_boundary` and `open_object`.
+
+## 0.5.0
+
+**Rule set `afp@1.4.0`.** Two classification defects are fixed and both move numbers,
+so a 0.4.0 baseline has to be recounted.
+
+Found by auditing a production count function by function against the code, rather than
+by reading the report's warnings — which is where the previous rounds had been looking.
+
+### Fixed
+
+- **Maintenance was decided per REQUEST instead of per store.** `behavior.writes`
+  decides EI against EO and was also read as "this store is maintained", so every store
+  a writing transaction touched became an ILF. A reference table merely READ by a route
+  that writes something else counted as maintained. On a production application this
+  left exactly one EIF in the whole count, which should have been the signal.
+- **Seeders, tests and factories counted as maintenance.** The project-wide pass read a
+  seeder's inserts as the application maintaining a table, so reference data only the
+  seed populates came out as an ILF — which the CPM does not allow. The filter on scan
+  roots drops `tests/` and `database/` only at the ROOT, and a domain-module layout puts
+  both inside `app/`. It now applies at any depth.
+- **The override warning counted floors that were already answered**, said "one schema"
+  whatever it was given, and therefore fired on a configuration that was complete.
+- **`opaqueReviewed` matching nothing was silent.** `detFromSchema` already warns when
+  it names a schema that is not declared; a review naming a field that does not exist
+  reviewed nothing while the warning kept firing, which reads as the tool ignoring the
+  configuration.
+- **A review was invisible in `fp:explain`.** Its reason appeared nowhere, which defeats
+  requiring one. Reviewed floors are now marked `(opaque, reviewed)` and the reason is
+  printed — without being counted in the "Declared by override" share, since a review
+  declares no number.
+
+### Documented
+
+- **In CI, prefer the standalone binary.** `node ace` validates `start/env.ts` before
+  running any command, so `node ace fp:count` fails on a missing environment variable
+  that has nothing to do with counting — measured on a production application, it
+  stopped at `Missing environment variable "AUTHZ_STORE"` and never reached the
+  command. The `fp:*` commands declare `startApp: false`, which is not enough. The
+  README said the two front-ends were interchangeable; for a pipeline that only checks
+  out code, they are not.
+
+### New
+
+- **`CallResolver.technicalWrite()`** declares that a write is not what the transaction
+  is for. §6.5.3 reads any write as an EI, which misreads a screen that records the
+  visit; the CPM asks about primary intent. The fact is declared about the CALL, so a
+  bookkeeping helper called from several screens is declared once. It does not hide the
+  write: the store stays an ILF and stays an FTR.
+- **`boundary.business` says when it contradicts the code.** It accepted without comment
+  a table nothing in the application writes — which is how two read-only lookup tables
+  were declared as business data on the belief they had a CRUD, when the routes were
+  `.only(['index', 'show'])`. The declaration is still honoured; the fact is reported.
+
 ## 0.4.0
 
 **Rule set `afp@1.3.0`.** Conditional validator groups now count, and a nested

package/README.md

@@ -13,7 +13,7 @@ node ace fp:count
 
 ```
 Unadjusted count: 46 FP
-Ruleset: afp@1.3.0
+Ruleset: afp@1.5.0
 
 type      n     FP
 ILF       2     14
@@ -34,18 +34,6 @@ GET /presenca                           EO       13    3    5
 GET /presenca/relatorio                 EO       13    3    5
 ```
 
-## Why
-
-Software factories bill by function point, and the count is manual, slow, and
-varies from counter to counter. Commercial automated counters exist for
-enterprise legacy, but **no modern framework has one** — not Laravel, not Rails,
-not AdonisJS. What those ecosystems do have (`rails stats`, `laravel-stats`,
-`adonisjs-stats`) counts classes and lines, which is a different thing.
-
-This package implements the OMG **Automated Function Points** specification,
-which defines how to automate IFPUG CPM by replacing the subjective judgements
-with deterministic rules.
-
 ## Install
 
 ```bash
@@ -53,80 +41,17 @@ npm i @filipebraida/adonis-function-points
 node ace configure @filipebraida/adonis-function-points
 ```
 
-Requires **AdonisJS 7** and **Lucid 22** (see [Support](#support)).
-
-### Or run it without installing
-
-For CI, or a one-off count on a project you do not want to touch:
+Requires **AdonisJS 7** and **Lucid 22** (see [Support](#support)). In CI, or
+for a one-off count on a project you do not want to touch, the standalone
+binary needs no install, no `.env` and no database:
 
 ```bash
 npx @filipebraida/adonis-function-points count --root ./my-app
 ```
 
-Nothing is booted either way — the engine only reads files — so a standalone
-run needs no `.env`, no database, and no install inside the analysed project.
-The standalone binary **does not replace installing**: a project that installs
-the package keeps the `node ace fp:*` commands, and both front-ends call the
-same code, so they cannot disagree about a number.
-
-```
-adonis-function-points <command> [options]
-
-  count                    count the unadjusted function points
-  inventory                the raw facts: stores, routes, tracing coverage
-  explain <name>           why one function was counted that way
-  diff <previous.json>     additions / modifications / deletions, and billable FP
-  calibrate <samples.csv>  correction factors against a manual count
-
-  --root <path>            application to analyse (default: the current directory)
-  --out <path>             write the result as JSON to this path
-  --json                   print JSON instead of a table
-  --min-coverage <0..1>    fail below this tracing coverage
-```
-
-Both front-ends exit non-zero when the count cannot be produced — coverage
-below the minimum, an unreadable configuration, a saved count from a different
-ruleset — so a CI job fails instead of publishing a number nobody can defend.
-
-#### In CI
-
-Every count records what it counted, so the artefact stands on its own once it
-leaves the pipeline:
-
-```json
-"source": {
-  "app": "shop",
-  "revision": "adef4ee3…",
-  "branch": "main",
-  "dirty": false,
-  "countedAt": "2026-09-24T17:40:11.000Z",
-  "config": "/app/config/function_points.ts"
-}
-```
-
-`dirty` is the field that matters in billing: a count taken over uncommitted
-changes cannot be reproduced from any revision, and whoever receives the
-invoice is entitled to know that. `app` is the manifest name, never an absolute
-path — a path would say where your machine keeps its files and travel with
-every count you send anywhere.
-
-`fp:diff` refuses two counts of different applications, the same way it refuses
-two different rulesets, and warns when either side is dirty or when both are
-the same revision.
-
-Counting an older revision needs no checkout of your working tree and nothing
-installed in it, so a pull request is two counts and a comparison:
-
-```yaml
-- run: git worktree add ../base ${{ github.event.pull_request.base.sha }}
-- run: npx @filipebraida/adonis-function-points count --root ../base --out base.json
-- run: npx @filipebraida/adonis-function-points count --out head.json
-- run: npx @filipebraida/adonis-function-points diff base.json head.json
-```
-
-The package does not deliver the result anywhere — an artifact, a ledger
-branch, a billing endpoint and a PR comment are all yours to choose. What it
-owes you is a number that is still defensible wherever it lands.
+Both front-ends call the same code and cannot disagree about a number. Which
+one to use where, what a saved count records, and how a pull request becomes
+two counts and a comparison: [`docs/ci.md`](docs/ci.md).
 
 ## Commands
 
@@ -144,73 +69,25 @@ saved count against the current state of the application. It deliberately does
 **not** take a git ref: booting an older checkout, with possibly different
 dependencies, is a problem not worth solving.
 
-### How change is priced
-
-AEP §6.5 gives explicit anchors for added (1) and deleted (0.4). For a **modified**
-function it grades the factor from 0.25 to 1.75 through Effort Complexity
-variation, which needs cyclomatic complexity this package does not measure — so it
-defaults to 1, which overestimates, and every diff says so with the amount at
-stake.
-
-What the default leaves on the table is a distinction the tool already measures:
-
-```
-changed      87 functions   378 FP  × 1
-  type              4 functions    23 FP
-  size             38 functions   204 FP
-  implementation   45 functions   151 FP
-```
-
-`implementation` means same type, same DET, same FTR, different body — a refactor.
-On a real pair of releases that was 151 of 378 FP billed as change. Pricing it at
-full functional value is not defensible, and pricing it at a number this package
-invented would be worse, so the number comes from the contract:
-
-```ts
-export default defineConfig({
-  diff: {
-    reasonFactors: { implementation: 0.25 },
-  },
-})
 ```
+adonis-function-points <command> [options]
 
-### `fp:metrics` — the counterweight
-
-If function points pay, the team optimises function points: more models, more
-endpoints, less reuse. So density and coupling are reported from the **same**
-inventory, and this command exists to put them on the same page as the number.
+  count                    count the unadjusted function points
+  inventory                the raw facts: stores, routes, tracing coverage
+  explain <name>           why one function was counted that way
+  metrics                  density, coupling and conformance, from the same run
+  diff <previous.json>     additions / modifications / deletions, and billable FP
+  calibrate <samples.csv>  correction factors against a manual count
 
-```
-Density
-  FP per data store:            27.0
-  transactions per data store:  5.4
-
-Conformance
-  inputs with a validator      100.0%   (30/30)
-  entry points with a handler  100.0%   (163/163)
-  data stores reached           96.7%   (29/30)
-  tracing coverage              95.1%   (15 unresolved calls)
-
-module                  FP  trans stores     I  depends on
-pedidos                211     33      8  0.60  inventores, tecnologias, users
-portal                  69     15      0  1.00  contato, documentos, inventores, ...
-inpi                    70     11      6  0.00
-
-Mutual dependencies (cycle candidates)
-  inventores <-> tecnologias
+  --root <path>            application to analyse (default: the current directory)
+  --out <path>             write the result as JSON to this path
+  --json                   print JSON instead of a table
+  --min-coverage <0..1>    fail below this tracing coverage
 ```
 
-The denominator of the first line is the transactions that **take** input, not
-every write. Measured over every write it read 39% on a healthy application, which
-invites the conclusion that 61% of its writes are unvalidated — and they are not:
-most are workflow triggers (`POST /orders/:id/submit`) that carry nothing beyond
-the route parameter. A metric that makes the reader draw a false conclusion is
-worse than no metric.
-
-`I` is Martin's instability, `Ce / (Ca + Ce)`: 0 means everyone depends on it and
-it depends on nobody, 1 means the reverse. A module at 0 that changes often is
-where change hurts. Cycles are **reported, not scored** — what to do about one is
-the team's decision, and a number would hide it.
+Every command exits non-zero when the count cannot be produced — coverage
+below the minimum, an unreadable configuration, a saved count from a different
+rule set — so a CI job fails instead of publishing a number nobody can defend.
 
 ### `fp:explain` — the number has to be defensible
 
@@ -236,72 +113,22 @@ Path walked:
 If function points get invoiced, someone will dispute a number — and a number
 without provenance is indefensible.
 
-## Benchmark
+### `fp:metrics` — the counterweight
 
-The only reference in this project not produced by its own authors is the case
-study published in **Vazquez, Simões & Albert (2011)**, the same one used by the
-COPPE/UFRJ dissertation on the _Ligeiro_ tool (Pinel, 2012).
-
-The fixture and the reference count were frozen in their own commit **before**
-the counter was ever run against them, with the transcription choices written
-down first. Without that the independence would be illusory.
-
-|                                     | total     | vs reference |
-| ----------------------------------- | --------- | ------------ |
-| **Vazquez et al. (2011), manual**   | **46 FP** | —            |
-| **this package**                    | **46 FP** | **0%**       |
-| Ligeiro, automated (Pinel 2012)     | 52 FP     | +13%         |
-| Ligeiro, manual under its own rules | 43 FP     | −6.5%        |
-
-Eight of the ten functions match exactly. The two that do not were **predicted
-in writing before the run**, and come from the standard rather than from
-defects:
-
-- **+1** `Consulta Apontamento Diário` is an EQ in the reference; AFP §6.5.3
-  requires collapsing EQ into EO, and an EO weighs more in the same band.
-- **−1** `Apontamento c/ Justificativa`: the IFPUG manual counts 1 DET for the
-  user message, AFP does not.
-
-They cancel out, which is exactly why the total is reported alongside the
-function-by-function agreement rather than on its own.
-
-Reproduce it with `npm test` — the benchmark is
-`tests/acceptance/vazquez.spec.ts`, and the reference is
-[`tests/fixtures/apps/vazquez/REFERENCE.md`](tests/fixtures/apps/vazquez/REFERENCE.md).
-
-## Principles
-
-**Traceability.** Every counted function says where it came from: file, line,
-rule applied, origin of each DET and each FTR, and the path walked through the
-call graph. The ruleset is versioned and printed in every report — two counts
-are only comparable if the rules did not change in between.
-
-**Say "I don't know" rather than be wrong in silence.** A call the tracer cannot
-follow enters the coverage metric. If coverage falls below the configured
-threshold, the analysis **fails** instead of emitting a number that looks right.
-This is not a preference; AFP §6.5.3 requires it:
-
-> "If the transaction execution depends on code that is unknown or unavailable
-> to the automated tool, the code end point shall be cataloged and listed in the
-> generated report in order to detect and quantify the missing patterns and
-> libraries."
-
-**Shape must not change the count.** The same logical application written in
-different ways — flat MVC or module-per-domain, fat controller or action object,
-generated artefacts or none — must produce an identical number. That is the
-project's golden invariant, and it is a test
-(`tests/acceptance/golden_invariant.spec.ts`) that was written before the first
-collector.
-
-**Extensibility as a requirement.** AdonisJS imposes no code organisation — fat
-controller, action object, static service, injected service, module function,
-job. Tracing strategies are registrable, so a project with its own convention
-registers it (see [Custom code pattern](#custom-code-pattern)).
-
-**Function points are not the only number on the dashboard.** If function points
-pay, the team optimises function points: more models, more endpoints, less
-reuse. Coupling, instability and density come free from the same inventory, and
-are the counterweight.
+If function points pay, the team optimises function points: more models, more
+endpoints, less reuse. Density, coupling, instability and conformance come free
+from the same inventory and are reported beside the number — what each metric
+means and what it deliberately does not measure: [`docs/metrics.md`](docs/metrics.md).
+
+### `fp:diff` — what change is worth
+
+Additions, modifications and deletions between two saved counts, priced by the
+factors the contract names: AEP by default, or `diff: { preset: 'sisp' }` for the
+Roteiro de Métricas do SISP v3.0 (inclusão 1,00, alteração × FI 0,63, exclusão
+0,50; `factors: { changed: 0.84 }` when the contractor did not develop the function). A modification is split by **why** it changed —
+type, size, or implementation only — so a refactor is visible before it is
+billed at full value. The reasoning, and what the default leaves on the table:
+[counting-decisions §5](docs/design/counting-decisions.md#5-identity-of-a-function-across-versions-fpdiff).
 
 ## Configuration
 
@@ -321,10 +148,11 @@ export default defineConfig({
     infrastructure: ['access_tokens', 'audits'], // excluded, with the reason in the report
     externallyMaintained: ['erp_customers'], // counted as EIF instead of ILF
     business: ['chat_sessions'], // the AFP naming filter caught it by accident
+    // technicalPatterns: [...DEFAULT_TECHNICAL_PATTERNS], // replaces the filter's naming list
     ignoreEntryPoints: ['prometheus.metrics'],
   },
 
-  retStrategy: 'constant', // or 'composition'
+  dataFunctions: { grouping: 'usage' }, // 'none' keeps every table its own data function
   maxDepth: 3, // how far to follow the call graph
   messageDet: 0, // 1 restores the IFPUG confirmation-message DET
   minCoverage: 0.85, // below this, the analysis fails
@@ -380,22 +208,25 @@ over a rate limiter or an attachment variant is a real example. Without a way
 to say so, such a call stays unresolved and drags the coverage gate down.
 
 ```ts
-const limiterIsDataFree: CallResolver = {
-  name: 'login-limiter',
-  order: 1,
-  resolve: () => [],
-  ignores(call) {
-    // true means: this is mine, and it touches no data store
-    return call.getExpression().getText().startsWith('this.loginLimiter.')
+import { ignoreCalls } from '@filipebraida/adonis-function-points'
+
+export default defineConfig({
+  resolvers: {
+    call: [
+      ignoreCalls({ name: 'login-limiter', matching: /^this\.loginLimiter\./ }),
+      ignoreCalls({ name: 'attachment-variants', methods: ['getUrl', 'getVariant'] }),
+    ],
   },
-}
+})
 ```
 
-`ignores` is asked before `resolve`, in the same order, so a later and more
-generic strategy cannot follow the call into a body it has no business reading.
-It is deliberately more expensive than a list of method names to silence: the
-volume still appears in the confidence block of `fp:count`, because a silent
-drop is the worst defect this package can have — whoever writes it.
+Or, for a shape the factory does not cover, a strategy with `ignores(call)`
+returning `true` — "this is mine, and it touches no data store". `ignores` is
+asked before `resolve`, in the same order, so a later and more generic strategy
+cannot follow the call into a body it has no business reading. It stays a
+**named** strategy on purpose: the volume it declared data-free still appears in
+the confidence block of `fp:count`, because a silent drop is the worst defect
+this package can have — whoever writes it.
 
 ## Support
 
@@ -415,9 +246,12 @@ Inherited from the AFP standard itself, not from this implementation:
 - **EQ is collapsed into EO.** Telling an inquiry from an output requires
   knowing whether there is derived data or calculation, which static analysis
   cannot see. AFP mandates the collapse.
-- **RET is approximated.** What a user recognises as a logical subgroup is not
-  derivable from code. The default pins it at 1; `composition` derives it from
-  composition relations.
+- **RET comes from usage, not from the user's view.** A `hasMany`/`hasOne`
+  child that no application code addresses directly folds into its parent as a
+  RET; one that has its own queries stays its own data function. That is the
+  only signal static analysis has, and it is conservative: it groups only when
+  the code cannot see the child apart from the parent. A child hanging off two
+  parents stays apart and is reported.
 - **Confirmation and error messages** count 1 DET in a manual count and are
   invisible here — a known systematic divergence of −1 DET per transaction.
   `messageDet: 1` restores it.
@@ -425,44 +259,42 @@ Inherited from the AFP standard itself, not from this implementation:
   judgement. AFP fixes VAF = 1, and the unadjusted count is what public
   contracts in Brazil use anyway.
 - **The modification factor in `fp:diff` is 1.** AEP grades it from 0.25 to
-  1.75 using Effort Complexity, which requires cyclomatic complexity. A flat 1
-  does not discriminate — it prices a one-line fix and a rewrite the same — and
-  the report says so.
-
-  What it does discriminate is **why** a function changed, which is usually the
-  larger question:
-
-  ```
-  changed      74 functions   318 FP  × 1
-    type              1 functions     3 FP     reclassified, e.g. EO -> EI
-    size             28 functions   141 FP     DET or FTR moved
-    implementation   45 functions   174 FP     same size, different code
-  ```
-
-  On a real month of work that is 44% of the invoice coming from refactoring.
-  Whether that should be billed at full value is a contract decision, not a
-  counting one — but it has to be visible before anyone can make it.
-
+  1.75 through Effort Complexity, which needs cyclomatic complexity this package
+  does not measure. A flat 1 prices a one-line fix and a rewrite the same, and
+  the report says so with the amount at stake. What it does discriminate is
+  **why** a function changed — type, size, or implementation only — and
+  `diff.reasonFactors` prices a refactor by the contract rather than by a number
+  the tool invented. See counting-decisions §5.
 - **Schema-driven applications undercount their input.** When the fields a user
   fills live in a JSON column whose schema is stored in the database, there is
-  nothing for static analysis to read: each opaque column counts as 1 DET.
-  Measured on a production application, the effect is about 2% of the total —
-  data functions are unaffected, and only the form-submission transaction loses
-  complexity.
-
-  `fp:count` names every opaque column a transaction reaches, so the limitation
-  is visible where you read the number rather than only in a design document.
-  The way out is to declare the number rather than let the tool guess it:
-  `overrides: { 'POST /petitions': { det: 42, reason: '…' } }`. The reason is
-  required by the type, `fp:explain` prints it beside the number, and `fp:count`
-  reports what share of the total was declared — because an override is right
-  where static analysis is blind and poison as a habit. See
-  counting-decisions §8.
+  nothing for static analysis to read: the column counts as 1 DET — a floor,
+  and `fp:count` names it on every run. The way out is to declare where the
+  fields live, by origin, and the declaration reaches every function that
+  carries the column:
+
+  ```ts
+  opaque: {
+    'Survey.answers': { schemas: 'surveySchema', reason: 'the form is a JSON Schema in the seed' },
+  }
+  ```
+
+  The reason is required, `fp:explain` prints it beside the number, and
+  `fp:count` reports what share of the total came from a declaration.
+  `overrides.<fn>.det` remains for a schema that lives only in the database.
+  See counting-decisions §8.
 
 - **Only HTTP routes are collected as entry points.** An ace command that
   imports a spreadsheet and a scheduled job are transactional functions under
   IFPUG; they are out of v1.
 
+## Benchmark
+
+The only reference in this project not produced by its own authors is the case
+study in **Vazquez, Simões & Albert (2011)**: 46 FP by hand, **46 FP** here, 8 of
+10 functions exact and the two that differ predicted in writing before the run.
+How the fixture was frozen, what Ligeiro got, and why the total is more
+defensible than any single function: [`docs/benchmark.md`](docs/benchmark.md).
+
 ## References
 
 - **OMG Automated Function Points (AFP) 1.0** — ISO/IEC 19515:2019. The
@@ -484,44 +316,32 @@ Inherited from the AFP standard itself, not from this implementation:
 
 The reasoning behind the count lives with the code:
 
-- [`docs/design/architecture.md`](docs/design/architecture.md) — the thesis, the
-  layers, and what is discovered instead of configured
+- [`docs/design/architecture.md`](docs/design/architecture.md) — why the package
+  exists, its principles, the layers, and what is discovered instead of configured
 - [`docs/design/counting-decisions.md`](docs/design/counting-decisions.md) —
   each edge case, with the AFP rule that settles it
 - [`docs/design/resolvers.md`](docs/design/resolvers.md) — the catalogue of code
   patterns and how each is followed
+- [`docs/benchmark.md`](docs/benchmark.md), [`docs/ci.md`](docs/ci.md),
+  [`docs/metrics.md`](docs/metrics.md)
 
 Three further documents are kept as a **dated record** of how the design was
 arrived at, in Portuguese, and are not a reference for current behaviour:
-[`implementation-plan.md`](docs/design/implementation-plan.md) (built phase by
-phase, and what each phase found),
-[`adonisjs-variation.md`](docs/research/adonisjs-variation.md) (what varies
-between real AdonisJS applications) and
-[`external-validation.md`](docs/research/external-validation.md) (the thesis
-tested outside the sample that produced it).
+[`implementation-plan.md`](docs/design/implementation-plan.md),
+[`adonisjs-variation.md`](docs/research/adonisjs-variation.md) and
+[`external-validation.md`](docs/research/external-validation.md).
 
 ## Contributing
 
 ```bash
 pnpm install
-pnpm test              # lint + 242 tests, from source
-pnpm run typecheck
-pnpm run compile && pnpm run test:package   # the packed tarball, installed and used
+pnpm test                                    # lint + the suite, from source
+pnpm run compile && pnpm run test:package    # the packed tarball, installed and used
 ```
 
-`test:package` is separate on purpose: the suite runs from source through
-ts-exec and never loads `build/`, which is the only thing a user gets. A
-release once had every `exports` path pointing at a file the build did not
-emit, with the whole suite green.
-
-Two house rules worth knowing before opening a PR:
-
-1. **Example first.** A fixture with a known answer comes before the code. A
-   fixture written after the code tests what the code does, not what it should
-   do.
-2. **A silent drop is the worst possible defect.** Anything the tracer cannot
-   follow must land in `unresolved` with the _right_ reason, never be quietly
-   treated as a read.
+Two house rules: a fixture with a known answer comes **before** the code, and a
+silent drop is the worst possible defect. The rest is in
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ## License