Eve library

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

Guide

Revision 1

On this page

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#

text
[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.