A file-based task manager
tsk-48: trust-model section in ARCHITECTURE.md
Documents what stable id does and doesn't promise (birth-name, not
immutability), the git-grain trust assumption, and why server-side
enforcement isn't on the table — common hosts don't expose per-
refspace permissions, so any integrity story has to live client-
side. Forecloses repeat misreads of the design as Option A
(immutable content) when it's actually Option B.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+40
+40
ARCHITECTURE.md
+40
ARCHITECTURE.md
···
123
123
pass that drops orphan property entries, ghost namespace bindings,
124
124
empty queues, and dangling queue index entries.
125
125
126
+
## Trust model
127
+
128
+
`tsk` borrows git's trust grain: if you accept a remote, you accept
129
+
its bytes. The stable id is the SHA-1 of the **birth** content blob —
130
+
the thing the task started life as — not a promise of immutability.
131
+
`object::update` rewrites the content blob whenever someone runs
132
+
`tsk edit`, and `git-pull` propagates those edits like any other
133
+
commit. A teammate with push access to your shared origin can
134
+
rewrite a task's body and the next pull will accept it. That's the
135
+
feature, not a bug.
136
+
137
+
What stable id *does* guarantee:
138
+
139
+
- The same content always hashes to the same id, on every clone,
140
+
forever. That's why `new_task` short-circuits to a reopen on
141
+
duplicate content (`Workspace::new_task`).
142
+
- An mbox patch series carries `X-Tsk-Stable-Id` and the receiver
143
+
verifies that the **first** commit's content blob hashes to it
144
+
(`patch::import_one_chain`). Tampered birth content is rejected.
145
+
- Per-namespace human ids (`tsk-N`) are minted client-side and can
146
+
collide across clones; `git-pull` resolves collisions by
147
+
renumbering local bindings (see the reconciliation matrix below).
148
+
149
+
What it does *not* guarantee:
150
+
151
+
- Immutability of the body after birth. Edits are commits on the
152
+
task ref's chain; `object::read` returns the tip's tree.
153
+
- Authenticity of the editor. Git author/committer fields are
154
+
self-asserted; tsk does not sign or verify them.
155
+
- Server-side enforcement. None of the common hosts (GitHub,
156
+
Forgejo, Tangled, GitLab) expose per-refspace permissions —
157
+
branch/tag protection only covers `refs/heads/*` and
158
+
`refs/tags/*`. Any stronger integrity story has to live in the
159
+
tsk client.
160
+
161
+
If your project needs body-level immutability or signed edits,
162
+
build it on top: pin a property like `signature: <sig>` on every
163
+
write and reject pulls that don't carry one. The current code base
164
+
deliberately doesn't.
165
+
126
166
## Sync flow: `tsk git-pull`
127
167
128
168
```mermaid