oficina / home Public

Download this file

1	# Review brief: escritorio's visibility model
2
3	You are reviewing a **design decision that has not been made yet**, not code.
4	Your job is to attack three options, then recommend one. Be adversarial. A
5	"looks fine" review is a failed review.
6
7	## Read these first (do not trust this brief's summary of them)
8
9	- `/home/paulca/amadan.net/oficina/home/docs/superpowers/specs/2026-08-30-home-design.md`
10	— the suite home's design. §0, §2.2, §3, §6 and ruling 9 are the load-bearing
11	parts. **Quote it rather than paraphrasing; do not invent rules it does not state.**
12	- `/home/paulca/amadan.net/oficina/home/AGENTS.md`
13	- `/home/paulca/amadan.net/oficina/sheets-core/AGENTS.md` — the sibling app's
14	binding rules, for house conventions.
15
16	## What is being designed
17
18	**escritorio** — a proposed new app in the Oficina suite (sheets, docs,
19	calendar, mail + the home). It is **one instance per team**, like Sheets is.
20	It is the team's front door. It does two things:
21
22	1. Launch links out to Sheets, Docs, Calendar, Mail for that team.
23	2. Show **one merged list** of that team's items across those apps.
24
25	**Settled already:** the index is **pointers only** — title, app, item ref,
26	URL, touched_at, actor person refs. No body text, no snippets, no
27	cross-app full-text search. Adding body text later is a separate decision.
28
29	**Why this app exists at all:** the home is centralised and must stay blind
30	(§0: "it never learns what is in anything"; §2.2: "Never renders content from
31	an instance"). So the home can never show a merged document list. The claim
32	being tested is that a **per-team instance** may hold what the centralised home
33	may not, because it shares a blast radius with the content it indexes.
34	**Attack that claim first.** If it is wrong, the whole app is wrong.
35
36	## Platform constraints (verify against the specs, don't take my word)
37
38	- Apps are rastrillo apps and **hibernate**. A request wakes them; there are no
39	timers while asleep. The home's spec drains its outbox "on wake and on each
40	share mutation, not on a ticker" for exactly this reason.
41	- Identity comes from the home as an assertion; `sub` is an opaque **person
42	ref**, stable across email change. Instances store person refs against grants.
43	- The home's directory is "a hint, never an authority" (ruling 9). Instances
44	re-check authorization on every request.
45
46	## The question
47
48	Escritorio must not show you the title of something you cannot see. Sheets and
49	Docs are the authority on sharing. How does escritorio filter?
50
51	**Option A — app posts the ACL; escritorio renders locally.**
52	Each pushed entry carries the person refs who may see it. Escritorio filters
53	from its own copy. No network on page load. Escritorio holds the sharing graph.
54	Between a revoke and the next push it can show a title to someone just
55	un-shared.
56
57	**Option B — escritorio asks the app at render time.**
58	Escritorio stores entries with no ACL. On each page load it asks each app "of
59	these refs, which may this person see?" The app stays sole authority; a stale
60	escritorio cannot leak. Page load fans out to ~4 apps, each of which may be
61	hibernating.
62
63	**Option C — Option A, plus revoke is a priority push.**
64	A revoke jumps the outbox rather than waiting for the next ordinary push. Lag
65	becomes seconds. Escritorio still holds the graph.
66
67	## Attack these specifically
68
69	1. **Is the per-team-instance justification sound**, or does escritorio just
70	re-create the aggregation risk the home was designed to avoid, one team at a
71	time? Does a team's escritorio have a *larger* blast radius than any single
72	app instance, since it spans four of them?
73	2. **Are titles actually low-value?** "Q3 layoffs — final", "Acquisition of
74	X — term sheet". Argue the case that pointers-only is not the cheap
75	concession it appears to be, and say what that implies for the choice.
76	3. **Option B and hibernation.** Is a cold wake of four apps on every front-door
77	load merely slow, or actually disqualifying? Does a short-TTL cache rescue
78	it, and if so does the cache re-introduce exactly Option A's staleness — i.e.
79	is B secretly A with worse latency?
80	4. **Option C's priority push.** Does it work when the *receiver* hibernates?
81	Trace it. What happens to a revoke if escritorio is asleep, if the push
82	fails, or if the pushing app dies mid-queue? Is "seconds" defensible or
83	marketing?
84	5. **Option A/C custody.** Escritorio holding `visible_to` person-ref lists is a
85	new copy of the sharing graph, per team. What does publishing escritorio's
86	database reveal, in the home spec's own "publish the database and see" form?
87	Write that sentence for each option.
88	6. **The unit is per-TEAM, but the user's stated want was "a list of MY sheets
89	and docs".** A person in three teams gets three escritorios and still has no
90	single list. Is per-team the right unit, or does this design answer a
91	different question than the one asked? This may be the most important finding
92	available to you — do not skip it.
93	7. **Anything a fourth option would fix** that none of A/B/C do. Propose it if
94	you find one; say so plainly if you don't.
95	8. **YAGNI.** Should any of this be built now, or does the suite need the home's
96	sign-in and directory (spec §13 steps 2–4) to exist first? Is escritorio
97	blocked on work that has not started?
98
99	## Output
100
101	- Findings, ordered by severity. For each: the claim, why it is wrong or risky,
102	and what it costs. Mark each **confirmed** (you verified it against a file)
103	or **suspected** (reasoning only).
104	- Then: **one recommendation** — A, B, C, or a fourth option — in a short
105	paragraph, with the single strongest argument against your own choice stated
106	honestly.
107	- Do not write code. Do not edit any file.
108