# Facets / Proprietary-Splitting in FVW v8 — Investigation

> **Question**: Has the proprietary-splitting pattern (facets) been written into the canonical FVW v8 in `avidtech6/freshvibestudio/pact/freshvibe-way-v8/`?
> **Short answer**: **No.** Zero hits for the pattern in v8 doctrine. The pattern lives only in `avidtech6/fv-module-gallery/gallery-pact/`. The `registry-plan.md` itself admits the FVW section it would belong in is **proposed, not written**: `FVW §17.12 (proposed)`.

---

## 0. The search results, cleanly

| What I searched for | Where | Hits |
|---|---|:---:|
| `facet` (case-insensitive) | `pact/freshvibe-way-v8/*.md` | **0** |
| `facet` | `pact/freshvibe-way-v9/*.md` | **0** |
| `src/.private` or `src/private/` | `pact/` (whole) | **0** |
| `proprietary` | `pact/` (excluding legacy / v9 recipes) | 4 hits, all in `pact/blueprint/...` and `pact/freshvibe-way-v6/v7`, all about the **tier** system, none about splitting |
| `public face` / `public surface` | `pact/` (whole) | 0 about visibility splitting; all about workspace surfaces |
| `facet` in `pact/` | 4 hits — all in `pact/platform/gallery/` meaning **"faceted browse"** (filter axes: kind / type / tier / surface / capability) — a completely different concept |
| `facet` in `avidtech6/freshvibestudio` commit history | All branches | **0** |

**Conclusion: the proprietary-splitting pattern (facets) has not been written into FVW v8.**

---

## 1. What FVW v8 actually says about modules

The relevant v8 sections are unchanged from v7 (per the v8 provenance headers). All three are about *which* module, *how to use* it, and *how to customise* it — none about *visibility slicing*.

### §10 — Modules as Clusters
- A module is a **cluster of related features** (5-6 features, e.g. calendar = show/pick/view/create/edit/delete)
- The **5-level hierarchy**: chip → behaviour → module → subsystem → app
- **20% / 50% override threshold** (under 20% = light, 20-50% = medium mirror, ≥50% = full fork)
- No mention of facets, visibility slices, public/private, or proprietary bits

### §11 — Recipe Book
- The 3-file model: `recipe.md` + `codex.md` + `rules.md`
- Per-module recipe books
- No mention of facets

### §17 — Modules and Tiers (the section that *should* contain facets)
- **One location, one constitutional document per module** (`modules/<name>/module.json`)
- **3 tiers**: `proprietary` (Tier 1), `off-the-shelf` (Tier 2), `generic` (Tier 3)
- **Tags** say role: `app`, `subsystem`, `workspace`, `module`, `card-primitive`, `engine-family`
- `tier_meta` object: `license`, `copyable`, `copy_requires`, `user_can_ship`, `user_can_edit`, `source_visible_in_fvs`, `generic_alternative`
- **§17.12 is proposed, not written.** The `registry-plan.md` in the gallery says "FVW §17.12 (proposed)" when describing the facets pattern. Searching the v8 file shows no §17.12 section exists.

### §18 — The Revibe Pattern
- An app's **local view** of an external module: pointers + handlers + forks
- §18.12 — **Catalog Visibility** table: which things appear in the catalogue (app's own modules, app's forks, canonical modules, mirror-state forks; NOT pointers, NOT hooks)
- §18.13 — "End of section. The shape is final."

So FVW v8's whole approach to "hiding" or "splitting" is at the **app level via revibe**, not at the **module level via facets**.

---

## 2. The 4 "facet" hits in `pact/platform/gallery/`

These are about **faceted browse** (filter categories in the Gallery UI), which is a different concept. From `pact/platform/gallery/gallery-contract.md` (Cluster T, FreshVibe Gallery, written 2026-06-17):

> **§7 CATEGORY AXES (4 — required minimum)**
> Every Gallery entry MUST be classifiable along 4 category axes. The axes are independent (faceted browse).
>
> | Axis | Values |
> |---|---|
> | `kind` | packaged-module / constitutional-doc / app-shell / platform-self |
> | `type` | primitive / system / composite / mega |
> | `tier` | proprietary / off-the-shelf / generic |
> | `surface` | chrome / workspace / content / interaction / … |
>
> A 5th axis (`capability`) is OPTIONAL but recommended.
>
> The Gallery's UI MUST support faceted browse along all declared axes. Click `chrome` to see all chrome entries; click `data` to see all data-capability entries; combine them to see chrome + data.

These are the **10 constitutional invariants of the Gallery** (per `gallery-ai-contract.md` §1):
- I.1 — Entry kinds are exactly 4
- I.2 — Module types are exactly 4
- I.3 — Tiers are exactly 3
- I.4 — The Gallery has exactly 5 surfaces
- I.5 — The Gallery registers itself
- I.6 — Reports are not entries
- I.7 — Promotion is the operator's call
- I.8 — Threshold-crossings are auto-reported (the 20%/50% rule)
- I.9 — The Gallery is dual-purpose until Studio exists
- I.10 — The Gallery is dual-surface in its UI

**No mention of facets-as-visibility-slices.** This is the Gallery's **filtering** model, not its **proprietary-splitting** model.

---

## 3. Where the pattern *does* exist

Three places, all in the gallery repo, none in FVW v8:

### 3.1 `avidtech6/fv-module-gallery/gallery-pact/registry-plan.md`

The full design doc. Section D, "The proprietary-splitting pattern (the missing piece)":

> *The use case*: You have a module that does the following:
> - Public features: 9-layer LLM dispatch, adapter registration, conversation history, basic error handling
> - Private features: Oscar-specific smart adapter, arboriculture standards, internal cache warming, custom rate-limit strategies
>
> *The solution*: facets. A module can have multiple **facets**. Each facet is a named subset of the module's exports.

It then defines:
- `default` facet (required, public)
- Named facets (e.g. `oscar-internal`, private, requires operator-agreement)
- `facets.json` schema
- The split: `src/default/` + `src/<facet-name>/` + `src/shared/`
- The rule: facets don't import from each other; shared code in `src/shared/`
- The visibility: barrel `index.ts` re-exports only the public surface; the AI can't see proprietary bits

It also lists 8 open questions for the operator in Section H, and in Step 2 of Section G says: *"Update the bundle manifest schema to support facets (if approved)"* — **"if approved"** is the conditional.

### 3.2 `avidtech6/fv-module-gallery/gallery-pact/facets.schema.json`

The full JSON schema, with `default` facet required and named facets optional. Declares:
- `exports: ["src/<facet>/index.ts"]`
- `visibility: "public" | "private" | "internal"`
- `license: "MIT" | "Apache-2.0" | "avidtech6-proprietary" | "avidtech6-proprietary-strict"`
- `requires: null | "license-key" | "operator-agreement"`
- `depends_on: ["module-id@^1.0.0", ...]`

### 3.3 `avidtech6/fv-module-gallery/gallery-pact/bundle-manifest.schema.json`

Has a `submodules[].visibility: "public" | "private"` field — but this is bundle-level visibility (whether a submodule is independently portable), not facet-level visibility slicing of a single module. **Different concept, same vocabulary.**

### 3.4 `avidtech6/fv-module-gallery/modules/ai-toast/facets.json`

The one **implemented** example. But it's empty:

```json
{
  "default": {
    "exports": ["src/default/index.ts"],
    "visibility": "public",
    "license": "avidtech6-proprietary",
    "requires": null,
    "description": "Public toast API..."
  }
}
```

Only the `default` facet. The `.private/` folder is empty. So even the one module that has the multi-facet shape uses only the simplest case.

---

## 4. The doctrinal gap, named

`registry-plan.md` is explicit that the pattern is **not yet in FVW** and the operator needs to decide:

> **Section G, Step 2**: "Update the bundle manifest schema to support facets (**if approved**)"

> **Section H, Open questions for operator**:
> 1. **Facets pattern — is this the right model?** The alternative is "split into separate modules" (e.g. `ai-ask` and `ai-ask-internal`). Which do you prefer?
> 2. Where does the public/private split live — in `module.json` or in a separate `facets.json`?
> 3. Forks in the same repo or separate?
> 4. Should `registry.json` be auto-generated or hand-edited?
> 5. Should the gallery be discoverable from the studio?

The `FVW §17.12 (proposed)` reference is the **placeholder where facets would go in FVW**. It's not written.

---

## 5. What this means for your migration / constitution work

Three options if you want to get facets into FVW v8 (or v9):

### Option A — Add a new section to FVW v8 (`pact/freshvibe-way-v8/`)
- File: e.g. `17.12-facets.md` or a new `36-facets.md`
- Content: lift Section D + Appendix A.1 of `registry-plan.md` into FVW doctrine
- 4-step process per the v8 `VERSIONING-RULES.md`: carry-forward with provenance, version bump, MIGRATION note, v8 → v8.1 changelog
- Last commit in fvs was 2026-07-21: *"v8.1: §38 — Two-Recipe Model and Plan-as-Seed"* — there's already v8.1 in progress

### Option B — Wait for FVW v9
- `pact/freshvibe-way-v9/` exists (with `00-STATE-2026-06-17.md`, `DOCTRINE-IMPLICATIONS.md`, etc.)
- Zero facet hits there yet, but v9 is the natural place to add new doctrine
- No `MIGRATION-v8-to-v9.md` exists yet — v9 is still in planning state

### Option C — Keep it gallery-only, reference from FVW
- Leave the facets doctrine in `fv-module-gallery/gallery-pact/`
- Add a 1-line note in FVW v8 §17 saying *"For module-level visibility slicing (public/private facets), see `avidtech6/fv-module-gallery/gallery-pact/registry-plan.md` Section D."*
- Lowest-effort, but doesn't constitutionalise the pattern

### Option D — Don't add it
- The current FVW v8 model (tier + revibe + 20%/50% rule) handles the operator's use cases adequately
- Facets is a solution looking for a problem — no module actually uses more than the `default` facet today
- If/when a real module needs the split (e.g. moving `ai-ask` into the gallery with its Oscar-specific internals), then add §17.12

---

## 6. Summary

| Question | Answer |
|---|---|
| Is the facets pattern in FVW v8? | **No.** |
| Is it proposed? | **Yes** — `registry-plan.md` references "FVW §17.12 (proposed)". |
| Is the schema done? | **Yes** — `facets.schema.json` is fully designed. |
| Is any module using it? | **Partially** — `ai-toast` has the shape but only the `default` facet; the `.private/` folder is empty. |
| Is the doctrine consistent across v6/v7/v8? | **Yes for the tier system** (3 tiers unchanged across v6→v7→v8). **No for facets** — facets don't exist in v6/v7/v8/v9. |
| Is it in the v8.x in-progress line? | **No** — the v8.1 work is §38 (Two-Recipe Model), not facets. |
| Is it referenced from any FVW file? | **No** — `grep` for "facet" across all of `pact/freshvibe-way-v8/` returns 0. |
| Is the gap documented? | **Yes** — `registry-plan.md` Section H has 5 open questions for the operator about facets, including "is this the right model?" |

The pattern is **designed and ready to be constitutionalised**, but it's a v8.2+ or v9 thing, not in current FVW v8 doctrine.

---

*Search performed on `avidtech6/freshvibestudio/pact/` (cloned 2026-07-21, 130+ root files) + freshvibestudio commit history (via API). 0 facet hits in FVW v8, 0 in v9, 4 in `pact/platform/gallery/` (all "faceted browse" meaning).*