Question: If two files have the same name, are they really the same project?
I wanted a simple rule: if I've already registered a project, don't register it again.
It sounded obvious. It wasn't.
The system I was building needed to know, every time a project got saved, whether it had seen this project before. If it had, reuse the existing ID. If it hadn't, create a new one. This is a common pattern — you look something up, and if it's not there, you create it.
The question was what to look it up by.
What I thought I needed
Every project had a filename. It felt like the obvious key — see
"quarterly-review.json" twice, and surely that's the same project.
I wired it up that way and moved on. It worked in every test I ran.
Where it broke
It broke the first time someone made an unrelated project with the same name.
Two people — or the same person, weeks apart — started two completely
different pieces of work, and both happened to end up with the exact same
filename. Nothing forced them not to. Filenames aren't reserved. Nobody
checks a global list before naming a new file "quarterly-review.json".
The second project didn't get a new identity. It got handed the first project's identity, quietly, with no error. From that point on, the system believed they were the same thing.
Why that was worse than it sounds
At first this looked like an edge case — two files, one weird collision, unlucky. But the more I looked at it, the less it looked like an accident and the more it looked like something the design had guaranteed would eventually happen.
Why filename? It was the only thing both sides of the system already agreed on. Convenient.
Why was that the wrong bar? Because convenient just means available, not reliable. I'd picked the filename because it happened to be sitting there, not because anything guaranteed it was unique.
Why names? Because a filename is a label a person chose, for reasons that have nothing to do with the system underneath it. Two people can choose the same label for two different reasons. That's not a bug in how people name things. That's just what names are for.
The real problem wasn't the collision. It was that I had asked a label to do a job only an identity can do — prove that this specific act of registering something is the same act as before, not just a similar- looking one.
What I changed
The filename didn't disappear. It just stopped being the system's source of identity.
Instead, every newly created project receives a registration key — a value generated once, stored with the project, and carried forward every time it is saved. That key, not the filename, is what the system checks against. Two projects can share a name freely now. They can't share the same registration key.
The trade-off is real: it's one more thing to carry around, one more field that has to survive being saved, reopened, and saved again. But it buys something a filename never could — a way to ask "have I seen this exact attempt before?" that doesn't depend on what anyone happened to call it.
I didn't need a better name.
I needed something that was never a name to begin with.
Wrong assumption: a shared filename means a shared project Discovery: identity can't be inferred from a label. It has to be assigned. Next step: even fixing this didn't finish the job — "saving" and "registering" turned out to be two different moments, and treating them as one caused its own problem. That's next.
The filename was never the problem.
Treating it as an identity was.