# Cybele Stub-Indicator Audit (V1-P2-2012)

**Date:** 2026-05-04 **Owner:** eng-cybele **Inputs:**
`scripts/stub-indicator-scan.sh` patterns + manual silent-stub sweep over
`libs/cybele/`. **Outputs:** Per-file verdict for every stub-indicator hit under
the Cybele domain plus a list of silent-stub findings (ignored parameters,
fabricated returns, simulated runtimes).

## TL;DR

The mandatory adversarial scan over `libs/cybele/**/src/` returns **61 raw
stub-vocabulary hits** plus **2 confirmed silent stubs** uncovered by the
silent-stub sweep. Both silent stubs were **REPLACE-now** and have been fixed in
this audit:

| Verdict                           | Count | Notes                                                                                 |
| --------------------------------- | ----- | ------------------------------------------------------------------------------------- |
| **REPLACE — fixed in this audit** | 2     | `tenant.ts:612` move-in checklist, `design-intelligence.ts:838` construction phasing  |
| **LEGITIMATE — domain term**      | 18    | Monte Carlo / energy `simulate*`, fixture providers, in-memory blockchain abstraction |
| **LEGITIMATE — test fixture**     | 28    | `fakeOnnx`, `fakeDrizzle`, `fakeRows`, `fakeDb`, fake fixture file I/O                |
| **LEGITIMATE — comment / config** | 13    | Production config docs, architectural notes, naming-only ('FAKE' string in a test)    |

No stub remained unaddressed after this audit. Two follow-up tickets are **not**
opened — every finding is either fixed or annotated as legitimate domain
language.

## 1. Silent-stub findings (REPLACE — fixed in this audit)

These were not surfaced by the vocabulary grep. They were caught by the
underscore-parameter pass and the "function ignores its inputs" pattern.

### 1.1 `libs/cybele/property/src/tenant.ts:612` — `generateMoveInChecklist(_recordId)`

**Before:** Static 10-item array; `recordId` ignored. Same checklist returned
for every onboarding record regardless of completed stages or outstanding
documents.

**After (this commit):** Reads the `OnboardingRecord`, walks its `stageHistory`
and `documentsRequired`/`documentsReceived`, and emits a checklist that:

1. Surfaces every outstanding required document as
   `Obtain outstanding document: <name>` items at the top of the list.
2. Skips lease-signing once `stageHistory` contains `lease_executed`.
3. Skips key-handover once `stageHistory` contains `keys_handed_over`.
4. Skips deposit-receipt confirmation once `deposit_paid` has been recorded.
5. Always includes inspection, meter readings, photos, welcome pack,
   property-management registration, MoMo mandate, and GIS pin update.
6. Names the assigned agent in the sign-off item, or otherwise asks the caller
   to assign one.
7. Throws (via `_get`) if the `recordId` does not exist — the function is no
   longer total over the input domain.

**Test coverage added** in `property-extended.test.ts`:

- outstanding documents appear at the top of the list and are exactly
  `documentsRequired.length - 1` after one document is received,
- `lease_executed` removes the "Sign lease agreement" item and the agent ID is
  surfaced,
- `keys_handed_over` removes the key-handover item,
- a missing `recordId` throws.

### 1.2 `libs/cybele/design/src/design-intelligence.ts:838` — `ConstructionSequenceGenerator.generate(elements, _buildingType)`

**Before:** The standard nine-phase RC frame sequence with phase durations
scaled only by element-count complexity. `buildingType` was typed as `string`
and silently dropped.

**After (this commit):** Introduces a `TYPE_PHASE_MULTIPLIERS` table keyed by
lowercase building-type tokens, covering the Cybele property catalogue
(residential, mixed-use, office, commercial, industrial, warehouse, hospitality
/ hotel, healthcare / hospital / laboratory, institutional / educational /
school, retail, civic). Each phase's `durationWeeks` is now
`baseWeeks * complexityFactor * typeMultiplier(phaseId)`, clamped to ≥ 1 week.
Unknown types fall through to the balanced `''` profile — the previous behaviour
— so existing callers keep their results.

Domain-specific deltas baked into the table (Ghana market sourcing):

- **Industrial / warehouse**: heavier substructure (P02 ×1.3) and slab / frame
  (P03 ×1.2), much shorter internal partitions (P06 ×0.4) and second-fix MEP
  (P07 ×0.6). No fit-out floor.
- **Hospitality / hotel**: long internal fit-out (P06 ×1.4), deep commissioning
  (P07 ×1.5), extended landscaping (P08 ×1.2).
- **Healthcare / hospital / laboratory**: HVAC-heavy first-fix (P05 ×1.5), very
  long second-fix and commissioning (P07 ×2.0), longer handover snagging (P09
  ×1.3).
- **Residential**: lighter MEP (P05 ×0.7) but more finishes (P06 ×1.2).

**Test coverage added** in `design-intelligence.test.ts`:

- industrial fit-out (P06) is shorter than hospitality fit-out,
- healthcare commissioning (P07) ≥ 1.5× office commissioning,
- unknown building types match the balanced default verbatim.

## 2. Vocabulary-grep classification (LEGITIMATE)

Each stub-vocabulary hit below was read in context. None require replacement;
reasons are recorded so a future scanner upgrade can mark them with
`// stub:legitimate <reason>` if/when their files are touched. No inline
annotations are added in this audit because the files have not been edited and
the pre-commit scanner only runs on staged diffs.

### 2.1 Domain "simulate" — energy & finance modelling

| File                                                  | Lines                   | Reason                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `libs/cybele/finance/src/proforma.ts`                 | 521                     | Monte Carlo perturbed input (`simulatedInput`) inside `runMonteCarloSimulation`; legitimate.                                                                                                                                                                                                                                                                             |
| `libs/cybele/design/src/digital-twin.ts`              | 151,640,643,672,697     | `EnergySimulationTwin.simulate()` — domain "simulate" with EnergyPlus-inspired regressions.                                                                                                                                                                                                                                                                              |
| `libs/cybele/design/src/sota-enhancements.test.ts`    | 343,344,354,359,368,381 | Energy-simulation tests verifying `simulatedEnergyKWhPerYr` < `baselineEnergyKWhPerYr`.                                                                                                                                                                                                                                                                                  |
| `libs/cybele/site-analysis/src/selection.ts`          | 41,895                  | Demographic weight + GIS imagery date comment ("simulated/modelled imagery"). Domain wording.                                                                                                                                                                                                                                                                            |
| `libs/cybele/site-analysis/src/site-analysis.test.ts` | 1733                    | Test comment ("Simulate a water body site by …") — naming-only.                                                                                                                                                                                                                                                                                                          |
| `libs/cybele/site-analysis/src/dem-provider.spec.ts`  | 189-196                 | Test comment ("Simulate the file-system check…") + fixture file marked `'fake'`.                                                                                                                                                                                                                                                                                         |
| `libs/cybele/proptech/src/blockchain-title.ts`        | 147                     | "Simulated blockchain state" — registry is a deliberate Ghana-Lands-Commission off-chain abstraction with cryptographic commitments (SHA-256 tx hash, ECDSA wallet signing wired in V1-P2-2011). No live chain is part of the V1 ship surface; the abstraction is the intended deliverable. Reason on file: deliberate off-chain registry with cryptographic primitives. |

### 2.2 Production / real-time docstrings (architectural notes)

| File                                                | Lines    | Reason                                                                                                                      |
| --------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `libs/cybele/db/src/connection.ts`                  | 18, 296  | DB pool tuning docstring + TLS section header — config docs, not behaviour.                                                 |
| `libs/cybele/site-analysis/src/ndvi-provider.ts`    | 170, 431 | Docstring on `utmZoneForLongitude` (STAC `proj:epsg` is source of truth in production) + `geotiffModule` override comment.  |
| `libs/cybele/api/src/gateway.ts`                    | 77       | Comment explaining the Hono sub-router topology vs a spread-out microservices deployment. Architectural note.               |
| `libs/cybele/api/src/circuit-breaker.ts`            | 252      | "data is rarely needed in real-time" — copy in a TTL comment.                                                               |
| `libs/cybele/api/src/routes/construction-ledger.ts` | 476      | Comment explaining duplication ("would create a cycle"); legitimate explanation.                                            |
| `libs/cybele/hospitality/src/revenue.ts`            | 194      | "Revenue gain = revenue from additional room sold that would otherwise be lost" — domain definition of overbooking benefit. |
| `libs/cybele/financials/src/synergies.ts`           | 20       | Synergy pricing range comment ("Max: market price (would not pay more than buying externally)") — domain definition.        |
| `libs/cybele/api/src/graphql/schema.test.ts`        | 19       | Test name ("returns seeded properties … instead of placeholder payloads") — describes a regression assertion, not a stub.   |

### 2.3 Test fixtures and fakes (`fake*`, `mock*`)

These are real test fixtures used to exercise the production code paths. Not
stubs.

| File                                                              | Reason                                                                                |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `libs/cybele/construction/src/drone-inference.spec.ts`            | `fakeOnnxModule` — synthetic ONNX session for YOLO/RT-DETR decoder tests.             |
| `libs/cybele/api/src/routes/properties-repository.spec.ts`        | `makeFakeDrizzle`, `fake.handle`, `fake.tables` — Drizzle test double for repo tests. |
| `libs/cybele/site-analysis/src/competitor-repository.spec.ts`     | `fakeRows`, `fakeDb` — Drizzle test double for competitor repo.                       |
| `libs/cybele/site-analysis/src/dem-provider.spec.ts`              | `'fake'` tile fixture file content for DEM cache test.                                |
| `libs/cybele/market-intel/src/market-intel-comprehensive.test.ts` | `'TXN-FAKE'`, `'FAKE'` — invalid IDs used to exercise error paths.                    |

## 3. Silent-stub patterns swept (and clean)

In addition to the vocabulary grep, the following patterns were swept across
`libs/cybele/**/src/*.ts` (excluding `*.test.ts` / `*.spec.ts` and
`node_modules`):

- **Underscore-prefixed parameters** that should be used. Two real hits fixed in
  §1; the remaining matches are private-readonly constructor fields actually
  used elsewhere in the class (`bim.ts:224 _entityExtractor`,
  `selection.ts:944 _bandProvider`), destructured loop variables
  (`construction/src/scheduling.ts:872`,
  `construction/src/resource.ts:92,110,214,366`,
  `design/src/sustainability.ts:538`), the API tracing memo
  (`api/src/tracing.ts:92`), the deliberately-noop fixture
  `FixtureDroneInferenceBackend.infer` and `FixtureNdviProvider.sample`, and
  `DrizzlePropertyRepository.appendValuation`/`reset` (the former delegates
  valuation persistence to a separately-owned table per the inline comment; the
  latter throws explicitly because `reset()` is an in-memory test affordance
  only — not a stub).

- **`Math.random()` in deterministic functions.** All matches under
  `libs/cybele/` are ID generation
  (`${prefix}-${Date.now()}-${Math.random()...}`). Tests and ID utilities only.
  No fabricated metric returns.

- **`createSimulated*()` / `MockClient` factories.** `git grep` returns zero
  matches under `libs/cybele/**/src/`.

- **`throw new Error('Not implemented'|'TBD'|'TODO'|'Unimplemented')`.** Zero
  matches under `libs/cybele/**/src/`.

- **`console.(log|warn|info)('Would ...`).** Zero matches under
  `libs/cybele/**/src/`.

- **Functions returning fixed literals (`return 80 + Math.random() * 20`).**
  Zero matches under `libs/cybele/**/src/`.

## 4. Per-file checklist summary

```
[clean] libs/cybele/api/                — gateway/auth/rate-limit/metrics, all comments architectural
[clean] libs/cybele/common/             — math, dates, geo, IDs (Math.random in ID gen only)
[clean] libs/cybele/construction/       — drone, ar-lidar, cost, procurement, progress, quality, scheduling
[clean] libs/cybele/core/               — types, guards, validators, serializers
[clean] libs/cybele/db/                 — schema, seed, connection (production-tuning docs only)
[fixed] libs/cybele/design/             — design-intelligence.ts:838 ConstructionSequenceGenerator.generate
[clean] libs/cybele/finance/            — proforma Monte Carlo, mortgage, REIT, crowdfunding, alternative-finance
[clean] libs/cybele/financials/         — cost-models, synergies, financials-extended, proforma-models
[clean] libs/cybele/hospitality/        — revenue, operations, hospitality-extended
[clean] libs/cybele/industrial-parks/   — operations, planning, warehouse
[clean] libs/cybele/infrastructure/     — civil-works, roads, procurement
[clean] libs/cybele/integration/        — bridges (asase, brigid, freya, maat, saraswati)
[clean] libs/cybele/market-intel/       — economic-indicators, pricing, supply, market-extended
[clean] libs/cybele/materials/          — concrete, steel, paint, tiles, furniture, cross-material
[clean] libs/cybele/prefab/             — modules, assembly, production, logistics, affordability
[fixed] libs/cybele/property/           — tenant.ts:612 generateMoveInChecklist
[clean] libs/cybele/proptech/           — blockchain-title (deliberate off-chain), wallet (V1-P2-2011), CRM, listings, transactions, digital-experience
[clean] libs/cybele/site-analysis/      — selection, dem/ndvi/borehole/EPA providers, GIS, demographics, infrastructure, land-registry, risk, ai-selection
[clean] libs/cybele/testing/            — fixtures, mocks (legitimate test infrastructure, not source)
```

## 5. Sign-off

All four conditions for the adversarial pass are satisfied:

1. Mandatory grep returns 61 hits, all classified above; zero unaddressed.
2. Every public function in `tenant.ts` and `design-intelligence.ts` that the
   audit touched has been read.
3. Every private delegate of those public functions has been read
   (`TenantOnboardingWorkflow._get`,
   `ConstructionSequenceGenerator.computeTotalDuration`).
4. The silent-stub pattern scan has been performed and reported in §3.
