The Changelog That Describes a Different System

I have been dropping warnings about the V6 CHANGELOG since part 1. This is the post where I cash them in, because the gap is not a rounding error — it is a changelog describing a different security system than the one V6 actually contains. Tables that do not exist, functions never written, triggers with no code behind them, columns for features that were never built. This post is how I found the drift, why it happened, and the rule it hammered home: in KC Star, the folder SQL is ground truth and the changelog is, at best, a proposal.

Two systems, only one of them real

Here is the actual RBAC implementation, the one from the folder SQL: three tables — PermissionTypes, HierarchyLevels, EmployeePermissions — and four routines — CheckPermission, GetEmployeePermissions, GetFilteredAnalyticalData, GrantPermission. That is V6's security model, entire. It is small, ordinal-based, and it works.

Now here is what the CHANGELOG says V6 contains:

• Tables EmployeePermission, PermissionLookup, RolePermission, SecurityAuditLog
• Functions CheckEmployeePermission, RevokePermission, CalculatePermissionAwareMeasures, GetFilteredSalesData, LogSecurityEvent, GetSecurityAuditLog
• Triggers TR_PermissionAwareFactCreation, TR_SecurityAudit
• Views EmployeePermissionView, PermissionAwareSalesView, SecurityAuditView
• Columns on Personnel: PasswordHash, PasswordSalt, FailedLoginAttempts, AccountLockedUntil

Read that list and you picture a serious authentication-and-audit platform: role-based permissions with a join table, a full security audit log, account lockout after failed logins, salted password hashing, triggers that create permission-aware facts automatically. It is a genuinely more ambitious design than what shipped.

None of it exists. Not one of those tables, functions, triggers, views or columns appears in V6/*.sql or in DatabaseV6.sql. The SecurityAuditLog is not there. RolePermission is not there. The Personnel table has no PasswordHash. The changelog is describing a system that was designed and documented but never implemented.

How I found it

I did not take either document on faith. The way you catch this kind of drift is to stop reading the prose and grep the code. I went through the changelog's object list and searched the actual SQL for each name:

grep -ri "SecurityAuditLog"  PostgreSQL/V6/  PostgreSQL/DatabaseV6.sql
grep -ri "RolePermission"    PostgreSQL/V6/  PostgreSQL/DatabaseV6.sql
grep -ri "PasswordHash"      PostgreSQL/V6/  PostgreSQL/DatabaseV6.sql
grep -ri "CheckEmployeePermission" PostgreSQL/V6/

Every one of those came back empty. Meanwhile the objects that do exist — PermissionTypes, CheckPermission, GetFilteredAnalyticalData — are nowhere in the changelog's list. The two documents describe disjoint systems. The code has three tables the changelog never mentions; the changelog has four tables the code never defines. That is not a version being slightly ahead of its docs. That is two independent artifacts that were never reconciled.

The lesson in the method: prose lies, grep doesn't. When documentation and code disagree, the code is the system. A changelog is a claim about the code, and claims need checking against the thing they claim about.

Why it happened

I can reconstruct the drift, and it is a mundane, extremely common failure. The CHANGELOG was written as a design document — a plan for what V6's security layer would be. Salted passwords, an audit log, role tables, permission-aware fact triggers: that was the ambition. Then, building it, I made the pragmatic choices the ordinal model describes — three tables, four functions, read-time filtering, no authentication at all (V6 assumes employees are already identified; it does authorization, not authentication). The implementation shrank to what the version actually needed. The changelog kept describing the plan.

Nobody updated the design doc to match the built system, because the design doc read like documentation and nobody re-verified it. It is the exact same species of drift as V5's two implementations and V4's forked lineage — a document and a codebase evolving independently — just at its most extreme, because here the document describes features that never got built at all rather than a variant that did.

The rule this enforces

This is the version that made my source-of-truth rule non-negotiable, so let me state it plainly: the folder split files are ground truth. The CHANGELOG count tables are approximate marketing. The V6 CHANGELOG specifically is fiction — a design that was not implemented — and must not be cited as documentation of the build.

Every article in this whole KC Star treatment follows that rule. When I describe what a version contains, I am describing the objects that exist in the numbered SQL files, verified by reading them. The changelogs are useful for intent — they tell you what I was aiming at — but they are not a reliable inventory, and V6's is actively misleading. If you ever build against KC Star, build against the folder, run grep on any object name a document promises you, and trust the result over the prose.

Why I kept the fiction

I could delete the misleading changelog. I have deliberately left it, because it is the single best teaching artifact in the project about a failure mode every codebase has: documentation drift, where the docs describe the system you meant to build and the code is the system you actually built. The gap between V6's imagined SecurityAuditLog and its real three-table model is a perfect, self-contained example of why “read the docs” is dangerous advice and “read the code” is the only safe one.

It also, honestly, records a real roadmap. Salted passwords and a security audit log are things a production version of this warehouse should have — the changelog is a decent wishlist for a V6 that went further. It just is not a description of the V6 that exists.

One more piece of V6's honesty remains, and it is operational rather than documentary: the fix scripts that repair a V6 database where the dimensions got seeded but the facts never generated — a half-run pipeline, caught and patched, and the hand-off to V7.