docs: Batch 9 — principals and canister computational model

[marc0olo]

Summary

• New page: `docs/concepts/principals.md` — the five principal classes and how caller identity works (self-authenticating IDs, canister IDs, anonymous principal, management canister, derived IDs)
• Expanded: `docs/concepts/canisters.md` — added two sections:
  • "Controllers" now includes the full control structure table (centralized / multi-sig / SNS-governed / immutable) and immutability verification
  • "### Upgrade" now includes the 3-step upgrade hook sequence (pre_upgrade → install → post_upgrade) and trap behavior
  • "Inter-canister messaging and error handling" covers the actor model, bidirectional request/reply, guaranteed reply, and trap/rollback semantics
• Fixed: `docs/concepts/canisters.md` line 73 — replaced Learn Hub principal link with internal `principals.md` link
• Updated: `docs/concepts/index.md` — added principals.md entry under Architecture with accurate description
• Updated: `docs/references/glossary.md` — updated principal entry to link to `concepts/principals.md`
• Deleted: 4 consumed Learn Hub staging files from `canister-smart-contracts/`

Content placement rationale

The "Canister Control" Learn Hub article was grouped with "What is a Principal?" in Learn Hub navigation, but the content (controller table, upgrade hooks) belongs with canisters under Diataxis. `principals.md` is focused on identity only; `canisters.md` absorbs all canister management content.

The "Computational Model" article is fully migrated into `canisters.md` (actor model, bidirectional messaging, guaranteed reply, trap/rollback in "Inter-canister messaging and error handling").

Staging files deleted

• `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/{what-is-a-principal,canister-control,canister-smart-contracts,computational-model}.md`

Sync recommendation

`principals.md`: `informed by Learn Hub article "What is a Principal?" (migrated, source retired)`
`canisters.md` additions: `informed by Learn Hub articles "Canister Smart Contracts", "Computational Model", "Canister Control" (migrated, source retired)`

[marc0olo]

Review notes

Two issues to fix before merge:

1. Broken link (blocking): principals.md links to ../guides/authentication/index.md, but that file does not exist. The guides/authentication/ directory contains internet-identity.mdx and verifiable-credentials.md but no index page. Options:

• Change the link to ../guides/authentication/internet-identity.md
• Remove the link and leave the mention as plain text

2. Third-party product link: The canister control structure table links to https://orbitwallet.io/ (Orbit wallet) as an example of a controller. Worth confirming whether linking to a specific third-party product is appropriate here, or whether a more generic description would be preferable.

No other issues: frontmatter complete, canisters.md expansion looks good, glossary.md and index.md updates are correct, <!-- Upstream: --> comment present, no banned patterns.

[marc0olo]

Review notes

Three items to address before merging:

1. Broken link in principals.md Next steps

The Next steps section links to ../guides/authentication/index.md, but that file does not exist. The authentication directory only contains internet-identity.mdx and verifiable-credentials.md.

Fix: change the link to ../guides/authentication/internet-identity.md.

2. Wrong self-authenticating principal example (line 16)

un4fu-tqaaa-aaaab-qadjq-cai is a canister principal (10 bytes, ~27 characters). Self-authenticating principals are derived from a public key hash (29 bytes) and encode to approximately 63-character strings, for example:

o2ivq-5dsbb-hhfso-w2o5v-7qiaq-g4fbm-6qhhb-xbj6w-szpxa-lflfa-mae

Using a canister-format string as a user principal example is misleading and will cause confusion for developers trying to understand what principals look like in practice.

3. Third-party product link decision needed

The canister control table includes a link to https://orbitwallet.io/ (inherited from the Learn Hub staging file). Other pages on this site use DFINITY-maintained or neutral references for examples. Please decide:

• Keep it with explicit context (e.g., "community wallet — Orbit") to set correct expectations, or
• Replace it with a generic description that does not endorse a specific product.

Neither option is wrong, but the choice should be intentional.

[marc0olo]

Feedback addressed:

• Wrong principal example: Replaced un4fu-tqaaa-aaaab-qadjq-cai (a canister-format principal) with o2ivq-5dsbb-hhfso-w2o5v-7qiaq-g4fbm-6qhhb-xbj6w-szpxa-lflfa-mae — a correct 29-byte self-authenticating principal derived from an Ed25519 public key
• Broken authentication link: Changed ../guides/authentication/index.md → ../guides/authentication/internet-identity.md (the actual file is internet-identity.mdx, resolved by Astro for .md links)
• Orbit wallet link: Kept the [Orbit](https://orbitwallet.io/) link in the control structure table — it serves as a concrete example of a multi-signature wallet in an explicitly labeled "Multi-signature" row, which gives sufficient context without requiring a prose explanation