One English word is doing four different jobs across our code and our design notes. This document picks one job for it to keep, renames the rest, and writes down the wrong turns so nobody has to take them again.
Decision recorded 2026-09-09 · counts re-measured the same day · companion to Portfolio architecture — the HOW
The decision. The word operator is being freed up in the shipped code and given to the company that runs a building day to day and whose rule book governs it — ConAm at Yale; Situs, Western Slope and Camellia each for their own buildings. The meaning the code uses today — “a human being, as opposed to Clara the AI” — becomes staff.
Read this table alone and you should be able to follow the whole document. The last column says where each word lives, because the same word can mean one thing in the shipped product and a different thing in the design notes — and that split is the entire reason this document exists.
Two phrases used in the last column. Shipped code means the software that is running right now for real customers. Design set means the written plans in docs/planning/portfolio-architecture/ — documents, not running software, so renaming there costs nothing but a find-and-replace.
| Term | What it means | What it is NOT | Where it lives |
|---|---|---|---|
| operator | The company that runs a building day to day and whose rule book governs it — the pet fee, the late fee, the tour policy all come from this company. It is an org-level role, meaning it attaches to an organization record (a company), and a property points at exactly one of them. | NOT a person. NOT a second, property-sized thing sitting beside the company — “one operator per property” and “operator names an org” are the same sentence said twice. | Design set future name. In shipped code it currently means something else entirely — see staff. |
| acting operator | The party holding the PropFlow account and running a building for an operator that has not signed up yet. “Acting” is the ordinary English word for doing a job without holding the office — an acting president, an acting manager. It cannot decide the operator’s rules — that is the whole point of the role and is unchanged. Amended 2026-09-10 (D-0910-1, b89017673): nor does it write them down on the operator’s behalf any more. This definition used to end “write the operator’s rules down but not decide them: transcribed, not authored”. A value the operator has not stated is now a blank falling to a PropFlow default. See the banner at the top. |
NOT a permanent role and NOT a rank. It exists only in the gap before the managing company onboards, and it disappears the moment they do. | Design set newly decided 2026-09-09. Applies today to exactly one property. |
| staff | A human being using PropFlow, as opposed to the AI. This is what the code’s current 'operator' value becomes: the list of who-did-this choices turns into 'system' | 'staff' | 'agent' — the software did it by itself, a person did it, or the AI did it. |
NOT a company. NOT specifically a PropFlow employee, even though a few older names such as org_propflow_staff and isPlatformStaff use it that narrower way. |
Shipped code already present and already meaning “a human” — see the note under the table. |
| agent | Clara — our AI. When a record says a change came from agent, it means the AI made it, not a person. |
NOT a real-estate agent. In the property industry “agent” normally means a licensed human who shows and leases apartments, so this word is a landmine when talking to customers. Inside the code it always means the AI. | Shipped code · conflicting industry meaning |
| org_admin | The top-level administrator person inside one of our customers — the human who can invite other humans and change that company’s settings. The founder ruled on this name previously and it stands. | NOT the operator — that is a company, this is a person. NOT “administrator” in the loose everyday sense of “whoever is in charge”. | Shipped code · also all over the design set |
| property owner / landlord | The outside party whose name is on the deed. May be granted reports and financial statements, and nothing more. | NOT a rung in the role hierarchy — it sets no policy and decides no rules. Owning a building and running a building are two separate facts. | Design set · industry |
| PMS credential holder | The login whose username and password the property-system sync actually runs under. A PMS is a property management system — the accounting-and-leasing software a company already uses, such as AppFolio — and we sign in to it as somebody. Today that login is stored in a field called Property.ownerId. |
NOT an owner, despite the field name. This is the third and last thing the word “owner” was being asked to mean, and the founder split it out. | Shipped code field, renamed in the design set |
| owner-operator | An industry phrase for the case where the owner company and the operator company are the same company. Situs owns buildings and also runs them, so Situs is an owner-operator. | NOT a third role, and it needs no row of its own anywhere. It is just two rows that happen to point at the same company. We use the phrase only when quoting the industry. | Industry · quoted in the design set · keep, never rename |
| custodian | Considered as the name for the managing company and rejected by the founder. Recorded here plainly so it is not proposed again. | NOT available even though it looks free: it appears zero times in shipped code and about a hundred times in the design set. It also reads as “janitor” in building vernacular, and an earlier design ruling had already spent it on the login-holder rather than the management company. | Rejected · currently in the design set, to be replaced |
| firm | Retired as a name for the management company. It was the design set’s placeholder word and it is going away. | NOT reusable for anything new, because in shipped code firm already means definite — a firm appointment as opposed to a tentative one. Retiring it from the design notes is fine; minting a brand-new firm… identifier is not. |
Retired from the design set · the unrelated “definite” sense stays in shipped code |
| manager / property manager | A person — a job title. If you walk into a leasing office and ask for the property manager, a human comes to the desk. | NOT a name for the company, and explicitly banned as one. Using it would put a job title and a corporate entity behind the same word, which is the exact mistake this whole document is undoing. | Shipped code (heavily) · industry |
| company / customer | The design set’s current word for the operator org — its ruling D1 reads “Company (= customer, wall, operator)”. If you are reading those notes, “company” in that position means what this document calls the operator. | NOT a fourth party. It is the same thing under an older label, and it will be read as operator from here on. | Design set current wording |
| fee manager / third-party manager | Real industry terms for a company hired by an owner to run a building it does not own. | NOT wide enough to be our word: they describe only the hired-hand case, and say nothing about an owner that runs its own buildings. | Industry only |
This role is small, and its limits are the whole point of it, so it gets its own section.
| Question | Answer |
|---|---|
| When does it exist? | Only in the gap before a managing company onboards onto PropFlow. In the normal case — Western Slope, Camellia, Situs — the operator holds its own login and there is no acting operator at all. |
| Where does it apply today? | Exactly one property: Yale. JP&Co owns it. ConAm manages it and is therefore the operator. ConAm has no PropFlow login, so JP&Co holds the account and acts for them. |
| What can it do? | Superseded 2026-09-10 by D-0910-1 (b89017673). This row used to read: “Write the operator’s rules down. Sean can enter the pet fee is $50, because ConAm says so, and the rule is stored attributed to ConAm.” That is no longer the mechanism that makes Yale answerable. The founder chose a PropFlow default instead: “anything will always just be a PropFlow default until the operator overrides it”. Hold the account, invite staff, keep the building running — but a policy value the operator has not stated is a blank that falls to a platform default, not a value typed on the operator’s behalf. |
| What can it NOT do? | Decide the rules — that part is unchanged and is the whole point of the role. What changed is the phrase: transcribed, not authored is no longer how the gap is filled. D-0910-1 is explicit that transcription is not thereby wrong — it “remain[s] the right machinery for a value a stand-in genuinely does transcribe from the operator” — it simply stops being the answer to the empty page. Sean is still not the author. |
| How does it end? | ConAm signs up, authors directly, and the role disappears. Yale sat under ConAm’s house from the start, so nothing is migrated. Amended by D-0910-1: the old reason given here — “the rules were attributed to ConAm the whole time” — no longer applies, because under the default the values were never written in ConAm’s name. An operator arriving now inherits blanks and platform defaults, and overrides them with an ordinary write — no grant, no permission step. |
| Candidate | Why it was attractive | Why it lost |
|---|---|---|
| caretaker | Technically perfect — a caretaker government holds office without setting new policy, which is precisely the limit we want. | Reads as “janitor” in a building context. The same problem that killed custodian. |
| stand-in | Instantly clear to anyone. | Too informal to live in a schema — that is, in the permanent field names and stored values that everything else is built on. |
| operator of record | The earlier working phrase for this role. | Replaced by the ruling above. No separate rationale was recorded, so none is invented here. |
“Right now we haven’t onboarded the bigger clients, so this would be the best time to do it.”
— the founder
The cost of a rename is not the cost of editing the code. It is the cost of the data — every row already sitting in the database with the old word written into it has to be found and updated, and every one of those updates is a chance to break something live. That pile only grows. It is smaller today than it will ever be again.
Right now “operator” means four unrelated things depending on which file you open. Three of them are ours; one is a quotation from Amazon’s documentation that only looks like ours.
| Sense | Plain-English meaning | Where it lives | Size |
|---|---|---|---|
| The human staff member | A person did this, as opposed to Clara the AI. It is one of three choices in a stored value: 'system' | 'operator' | 'agent'. |
Shipped code — src/ and agents/ |
4,553 hits 1,444 files 953 product, 491 test |
| The provisional login-holder | The stand-in administering a building before the real operator onboards. Now named acting operator. In the design set this shares the word custodian with the sense below — there it names “the single party that writes the rules for a property”, whoever that happens to be, which is exactly why the two senses blur together. |
Design notes only — never shipped | 107 hits on 97 lines as custodian |
| The management company | The founder’s intended sense — the company that runs the building. Currently written as firm. |
Design notes only | 495 hits design set |
| Amazon policy grammar | Nothing to do with people or companies. An “operator” here is an instruction for merging settings — like add to or overwrite. | Design notes, quoted beside Amazon’s own documentation links | 11 hits 6 verbatim Amazon + 5 modelled on it |
Counts are mine, re-measured on 2026-09-09 — see §9 for the exact command, the exact checkout, and how they compare to the earlier scoping pass.
Expand/contract is the name of the shape. First you expand what the software will accept, so it understands both the old word and the new one at once. Only after every stored row has been converted do you contract — remove the old word. The two words overlap for a while on purpose.
operator and staff as the same thing. Nothing changes in how the product behaves; it just becomes more forgiving. Zero riskstaff. New rows are written with the new value. Old rows are still out there and are still read correctly, because of step 1. Reversibleauthority, by, evidence, reason, source, triggerActor. Data writefirm becomes operator, and the provisional login-holder becomes acting operator. Design set onlyThese are variable and field names that contain the word. Counts are how many times each appears in src/ and agents/ today.
| Identifier | Hits | Note |
|---|---|---|
operatorId | 13 | |
operatorSid | 15 | |
operatorDomains | 42 | |
operatorStageHold | 16 | |
isOperatorInitiated | 15 | |
interruptedByOperator | 10 | |
operatorOrgId | 10 | The one that forced this. The design set wanted to mint that exact name for a completely different party — the management company. Two different things, one name, no warning from any tool. |
A find-and-replace that is too eager does real damage here. Four categories are off limits.
owner-operatorThe correct industry term, used correctly. It appears about 50 times in shipped code and roughly 75 times in the design set. Leave every one of them alone — renaming a term of art makes our writing wrong, not cleaner.
In Amazon’s configuration language, an “operator” is an instruction about how a child setting combines with a parent setting — overwrite it, add to it, remove from it. It has nothing to do with people or companies.
| Identifier | Hits | What it actually is |
|---|---|---|
operators_allowed_for_child_policies | 6 | Verbatim Amazon. Quoted in the design notes directly beside the Amazon documentation URL it came from. Renaming it would falsify a citation to somebody else’s published documentation — the quotation would no longer say what the source says. |
constraintOperator | 4 | Ours, not Amazon’s — a proposed field in the design set, modelled on the Amazon grammar above. Still off limits, because the word here means a merge instruction, not a company. |
childOperators | 1 | Same: our own proposed field name, borrowed from the Amazon pattern. Same reason to leave it. |
Worth being precise about the difference, because the two buckets need different care: the verbatim one must never change at all, and the two modelled ones must simply never be swept up by a rename aimed at the human sense.
firm in shipped codeAn unrelated adjective meaning definite, as in a firm appointment versus a tentative one. It appears 871 times in src/ and is entirely correct there.
| Where | Hits | Meaning |
|---|---|---|
scheduleKind === 'firm' | 1 | This appointment is confirmed, not penciled in. |
firmDate | 44 | The settled date. |
firmTime | 31 | The settled time. |
firmSignal | 20 | Evidence that a time is settled rather than proposed. |
Retiring “firm” from the design set is fine. Minting any new firm… identifier is not — the word is spoken for.
These are unrelated and would be destroyed by a careless search-and-replace.
| Word | Hits in src/ | Meaning |
|---|---|---|
confirm… (confirmDate, confirmed, …) | 13,099 | To make certain. Nothing to do with a company. |
affirmative | 158 | A yes answer. |
reaffirm | 1 | To confirm again. |
firmographics | 0 | Marketing data about companies. Zero today — listed so it is not accidentally invented later. |
Every one of these was seriously proposed. This table exists so the next person does not spend an afternoon arriving at the same answers.
| Word | The case for it | Why it lost | Evidence |
|---|---|---|---|
| manager | It is what people actually say out loud: “who manages that building?” | It collides with a human job title — a property manager is a person who sits at a desk. And manager_party already exists in the design set, so the word is doubly spoken for. |
3,185 in src/27 manager_party |
| administrator | Generic, formal, sounds institutional. | Collides with org_admin, which the founder already ruled on for a different party — the top-level person inside a customer. Reusing the same root for a company would undo that ruling. |
543 org_admin5,672 admin-family |
| custodian | Technically ideal. Zero occurrences in shipped code — a completely clean word — and the design set had already used it about a hundred times for roughly this concept. | The founder rejected the word. Recorded plainly, as the decision it is. Two supporting reasons: it reads as “janitor” in property vernacular, and an earlier design ruling had already spent it on the login-holder rather than the management company — so it was not as free as it looked. | 0 in src/107 hits on 97 design-set lines |
| fee manager / third-party manager | The real industry terms. Nobody would need them explained. | They describe only the hired-by-an-owner case. They do not cover an owner that operates its own buildings — which is Situs, one of our actual customers. A name that cannot describe a live customer is not a name. | — |
| runner | Short, plain, “runs the building” is literally the definition we want. | Already taken, heavily. In our code a runner is a browser or job runner — a background process that executes work. | 2,210 in src/ |
During this investigation two measuring tools returned answers that were wrong. Both looked exactly like right answers: a number, no error, no warning.
Two independent tools agreed exactly, which is the other half of the check:
| Command | Result |
|---|---|
grep -roiE '\boperator' src agents | wc -l | 4,553 |
rg -oiN '\boperator' src agents | wc -l | 4,553 |
git grep -oE '\btenant' origin/main -- src | wc -l | 0 — false |
grep -roiE '\btenant' src | wc -l | 23,666 — true |
So that anyone can reproduce or challenge them:
| Setting | Value |
|---|---|
| Pattern form | \bword — word-start only, no closing boundary, case-insensitive. This is the form that counts operatorId as a hit, which is what a rename needs to know. |
| Scope | src/ and agents/ for shipped code; docs/planning/portfolio-architecture/ for the design set. |
| Checkout | wt/astra-arch-review at branch astra/arch-review — a branch is one named line of work, a parallel copy of the code — at commit 4f49cde, a commit being one saved snapshot of that line. Not origin/main, which is the shared trunk everyone merges into. |
| Tool | ugrep 7.8.4, cross-checked against ripgrep. |
| Date | 2026-09-09. |
The brief’s figures were measured at origin/main; this branch has moved since, and the design set in particular is being actively rewritten. The gaps below are consistent with that drift, not with a disagreement about method — the firm count matching to the digit proves both of us used the same pattern form.
| Claim | Brief | Re-measured | Verdict |
|---|---|---|---|
firm in src/ | 871 | 871 | Exact |
manager in src/ | 3,189 | 3,185 | Confirmed (branch drift) |
runner in src/ | 2,212 | 2,210 | Confirmed (branch drift) |
custodian in shipped code | 0 | 0 | Exact |
custodian in design set | ~110 | 107 (on 97 lines) | Confirmed |
Files touched by operator | 1,440 958/482 | 1,444 953/491 | Confirmed (branch drift) |
Total operator occurrences | 4,257 | 4,553 | Higher here — branch drift |
| The six literal-bearing fields | 6 | 6 | Exact — same six names |
Literal 'operator' sites | 39 | ~49 | Higher here — 41 assignments + 8 comparisons |
org_admin in shipped code | 495 | 543 | Higher here |
| Admin-family in shipped code | 5,383 | 5,672 | Higher here |
owner-operator | 37 | 50 code / 75 design | Scope unclear — no scope reproduces 37 |
firm in the design set | 914 | 495 | Unreproduced — no scope I tried lands on 914 |
| “operator of record” lines | ~351 | 0 | Not found — see below |
| Item | Status |
|---|---|
| “Operator” means the company that runs the building | Decided |
| Operator is an org-level role; one per property; no property-level entity | Decided |
| “Owner-operator” is not a third role | Decided |
The code’s sense becomes staff | Decided |
| The provisional login-holder is the acting operator | Decided 2026-09-09 |
custodian, manager, administrator, fee manager, runner as names for the company | Rejected |
| Expand/contract, five steps, in that order | Decided |
Exact new field name replacing Property.ownerId | Resolved in the design set as pmsCredentialUserId (loop-answers-Q1-Q28-2026-09-07.md, Q5) |