api_version: modusbrain-schema-pack-v1
name: gbrain-base-v2
version: 1.0.0
migration_from:
  pack: gbrain-base
  version: "1.x"

┌────────────────────────────────────────────────────────────────┐
│  PACK AUTHORING                                                │
│                                                                │
│  Author declares: migration_from: {pack: P, version: R}        │
│  + mapping_rules: [retype/page_to_link/page_to_alias]          │
│  Pack ships bundled OR via ~/.modusbrain/schema-packs/<name>/      │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  ONBOARD CHECK DISCOVERY                                       │
│                                                                │
│  checkPackUpgradeAvailable(engine) at src/core/onboard/        │
│  checks.ts:                                                    │
│    1. Read engine.getConfig('schema_pack') for dbConfig tier  │
│    2. loadActivePack({cfg: null, remote: false, dbConfig})    │
│    3. findPackSuccessors(active.name, active.version)         │
│         → walks BUNDLED_PACK_NAMES + ~/.modusbrain/schema-packs/   │
│         → matches via _versionRangeMatches(version, range)    │
│         → returns ResolvedPack[] sorted by successor version  │
│    4. If successors.length > 0, emit OnboardCheckResult        │
│       with RemediationStep targeting `unify-types` handler    │
│       + protected: true (D17 → manual_only via render          │
│       allowlist)                                               │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  USER DECIDES                                                  │
│                                                                │
│  modusbrain onboard --check shows finding                          │
│  modusbrain onboard --check --explain shows per-cluster narrative  │
│  User reviews; if OK, runs:                                    │
│    modusbrain jobs submit unify-types --allow-protected \          │
│      --params '{"target_pack":"gbrain-base-v2"}'               │
│  (Autopilot never auto-fires this; manual_only)                │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  HANDLER EXECUTION (src/core/schema-pack/unify-types-handler.ts) │
│                                                                │
│  1. Preflight: load target pack; assert mapping_rules present  │
│  2. Stats snapshot (pre-state for celebration)                 │
│  3. Acquire modusbrain-unify db-lock (60min TTL)                   │
│  4. Apply phases (4):                                          │
│     a. Explicit retype rules (chunked UPDATE 1000/batch)       │
│        - frontmatter.legacy_type ALWAYS preserved (D8)         │
│        - frontmatter.subtype stamped when subtype set          │
│     b. Catch-all retype: synthesize per-unknown-type rule       │
│        excluding declared types + explicit targets + page_to_  │
│        link/alias sources (D12 + critical bug fix)             │
│     c. Page-to-link: parse body+frontmatter, insert link row,  │
│        soft-delete source page (per-page atomicity per F7)     │
│     d. Page-to-alias: insert slug_aliases row, soft-delete     │
│        source page (NO rewriteLinks per D15)                   │
│  5. Final sync: path-prefix typing for residual UNTYPED rows   │
│  6. ACTIVE-PACK FLIP (D13):                                    │
│     - engine.setConfig('schema_pack', target_pack)             │
│     - saveConfig({...existing, schema_pack: target_pack})      │
│  7. Verify: re-run stats; warn if ≤ declared + 5 violated      │
│  8. Celebration summary to stderr + audit JSONL                │
│  9. Release db-lock                                            │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  POST-UPGRADE STATE                                            │
│                                                                │
│  • pages.type updated with canonical types                     │
│  • frontmatter.legacy_type preserved for rollback              │
│  • slug_aliases populated for old-slug → canonical lookup      │
│  • links table has new partner_of / relates_to rows            │
│  • Source pages soft-deleted (72h TTL for restore)             │
│  • Active pack flipped to target_pack                          │
│  • Next modusbrain onboard --check shows ok                        │
└────────────────────────────────────────────────────────────────┘

api_version: modusbrain-schema-pack-v1
name: modusbrain-academic-v1
version: 1.0.0
description: Academic research brain — adds researcher canonical
modusbrain_min_version: 0.42.0
extends: null

migration_from:
  pack: gbrain-base-v2
  version: "1.x"

page_types:
  # Inherit gbrain-base-v2's 15 types here (or use extends to merge
  # automatically once v0.43+ extends-chain composition lands)
  - { name: person, primitive: entity, path_prefixes: [people/], expert_routing: true }
  - { name: company, primitive: entity, path_prefixes: [companies/], expert_routing: true }
  # ... all 13 other v2 canonicals ...
  - { name: note, primitive: concept, path_prefixes: [notes/], extractable: true }
  # Academic addition:
  - name: researcher
    primitive: entity
    path_prefixes: [researchers/]
    aliases: [academic, professor, scholar]
    extractable: false
    expert_routing: true

mapping_rules:
  # All v2 mapping rules (copy from v2 yaml)
  # ... ~40 rules ...
  # Custom: relocate v2-tagged academics to researcher
  - { kind: retype, from_type: person, to_type: researcher, path_filter: 'researchers/%' }
  # Catch-all
  - kind: retype
    from_type: "*unknown*"
    to_type: note
    subtype_field: legacy_type
    subtype: "*original_type*"