feat: decouple intent/code from core so braid is a pure framework (ontology-declared SourceRoles)

[mroops0111]

Summary

braid is meant to be a pure framework where the ontology is a plugin (DDD is just the default). But the intent / code worldview is still hard-coded into core, which blocks any non-software ontology (for example a research-notes ontology with roles note / reference) from being a first-class citizen.

This issue tracks decoupling the source-role taxonomy from core so braid is genuinely "braid anything". The bar is OCP: adding a new ontology with its own source roles must require zero edits to @braidhq/core and @braidhq/schema.

Guiding principle

The framework must never branch on a role's identity. It branches only on a capability the ontology declares for that role.

Every leak below is the same violation, asking "are you the thing called intent?" (role === 'intent', mode === 'intent', kind === 'source-intent'). The fix is to ask instead "do you have the capability its sources are enumerated into batch units?". The role name disappears from the framework; the capability stays. The Information Expert for role semantics is the ontology plugin, not core, not the source, not the role name.

Current leaks (verified inventory)

Single root:

• packages/schema/src/source.ts SourceRole = z.enum(['code', 'intent']). A closed enum pins the taxonomy. Everything downstream is either this enum flowing through SourceDescriptor.role, or a literal comparison against it.

Framework branches on role identity (these are the OCP violations):

• packages/core/src/domain/workspace/Workspace.ts codeSources() / intentSources() filter on the literal role.
• packages/core/src/application/BatchService.ts resolveMode (intent vs code vs derive), the mode === 'intent' branch, and buildIntentUnits / IntentLister.
• packages/core/src/application/ReactorService.ts isIntentSource gates reactive re-derivation on role === 'intent'; code sources fall through.
• packages/schema/src/batch.ts BatchInputMode = z.enum(['intent', 'derive']). The intent value is a framework mode name borrowed from the role.
• packages/schema/src/skill.ts SkillInputSourceIntentProvider (kind: 'source-intent') enumerates only role:intent sources for skill forms.
• packages/core/src/domain/plugin/OntologyPlugin.ts requiredSourceRoles is the only role hook an ontology has, and it is typed readonly ('code' | 'intent')[]. Same narrow type is duplicated in packages/sdk/src/defineOntologyPlugin.ts.

Server:

• packages/server/src/infrastructure/source/intentScan.ts skips any role !== 'intent' source.
• packages/server/src/routes/skills.ts rejects a sourceUnit whose source is not role === 'intent'.
• packages/server/src/routes/ontology.ts and packages/schema/src/ontology.ts OntologyResponse expose node and edge types but not roles, so no client can learn an ontology's role vocabulary.

Client:

• packages/studio/src/lib/sourceDraft.ts rolePathSegment hard-maps role to the intents / codebases folder.
• packages/studio/src/components/AddSourceDialog.tsx and CreateWorkspaceWizard.tsx hard-code the two roles as dropdown options, defaults, and labels.
• packages/studio/src/pages/Batch.tsx carries DDD-specific prose ("Reads every registered intent doc", "Will Scan Codebases") that a non-software ontology would render wrong.

Already generic (leave as-is, these are the pattern to follow):

• packages/core/src/application/WorkspaceService.ts assertRequiredSourceRoles already diffs presence against a declared list.
• packages/schema/src/source.ts LoaderKind is already an open branded string ("new loaders need no edit here"). This is the exact precedent for SourceRole.
• packages/core/src/domain/validation/validateEvidence.ts drift surfacing is already generic (it renders driftIssues that upstream skills write). Only the two named flags metadata.intentMissing / implementationMissing (packages/schema/src/model.ts) still bake the worldview in.

Proposed design

1. Open the role type

SourceRole becomes an open branded string, matching the LoaderKind precedent. The intent / code values leave @braidhq/schema and become data the DDD ontology declares.

export const SourceRole = z.string().min(1).brand<'SourceRole'>()

2. Ontology declares a role vocabulary with capabilities

requiredSourceRoles is replaced by a descriptor list on OntologyPlugin. The capability, not the name, is what the framework reads.

export interface SourceRoleDescriptor {
  readonly id: SourceRole
  readonly label: string
  /** Sources of this role must be present for the ontology to run. */
  readonly required?: boolean
  /**
   * Sources of this role are enumerated directly into batch units,
   * and their sync triggers the Reactor. The name is provisional.
   */
  readonly unitBearing?: boolean
  /** Workspace subfolder these sources provision into. */
  readonly pathSegment?: string
}

// on OntologyPlugin, replacing requiredSourceRoles
readonly sourceRoles: readonly SourceRoleDescriptor[]

required is derived by sourceRoles.filter(r => r.required), so assertRequiredSourceRoles keeps working unchanged. unitBearing is a single capability that drives both batch unit production and reactor gating. They lock onto the same set of sources, so they do not need separate flags. A future divergence can add a second capability without breaking anyone.

3. Framework derives batch behavior from the capability

BatchInputMode stays a closed framework enum (two exhaustive modes) but loses the role name:

export const BatchInputMode = z.enum(['direct', 'derive'])

BatchService decides purely from declarations, with no role literal:

private resolveMode(workspace, ontology, binding): BatchInputMode {
  const unitRoles = ontology.sourceRoles.filter(r => r.unitBearing).map(r => r.id)
  if (unitRoles.some(role => workspace.sourcesWithRole(role).length > 0))
    return 'direct'
  if (binding.deriveUnits)
    return 'derive'
  throw new ValidationError(...)
}

Layering: Workspace exposes a pure sourcesWithRole(role: SourceRole), replacing intentSources() / codeSources(). The domain never learns which roles are unit-bearing; the application layer, which already resolves the ontology, does that lookup and calls back into the pure accessor. Domain stays free of the plugin registry.

The same unitBearing capability re-points four call sites: resolveMode, ReactorService.isIntentSource (becomes isUnitBearingSource), intentScan (becomes a generic unitScan injected as unitLister), and the sourceUnit guard in routes/skills.ts.

4. Skill-input source provider becomes role-parameterized

export const SkillInputSourceProvider = z.object({
  kind: z.literal('source'),
  filter: z.object({
    role: SourceRole.optional(),
    loaderKind: z.string().optional(),
  }).optional(),
})

The DDD extract skill declares role: 'intent' itself. The framework and Studio only know the role parameter.

5. Expose roles to the client

OntologyResponse gains sourceRoles (id, label, capabilities). Studio's Add-Source dropdown, wizard defaults, rolePathSegment, and the Batch-page copy all become driven by the active ontology's declared roles instead of hard-coded literals.

6. SDK

@braidhq/sdk re-exports the SourceRole type, and defineOntologyPlugin takes sourceRoles in place of the narrowly-typed requiredSourceRoles.

7. Evidence flags (coordinate with #68)

Generalize metadata.intentMissing / implementationMissing into a role-agnostic notion of "no evidence yet from role X". This is the cross-role corroboration model that #68 (trust for domains with no privileged fact source) also needs, so the two should be designed together rather than piecemeal.

8. Tests

Framework and @braidhq/test-utils fixtures move to a neutral test ontology (for example roles alpha / beta). Any test that legitimately exercises intent / code moves into packages/ontology-ddd/test.

Acceptance criteria

• A third-party ontology can declare its own SourceRole set and run the full extract, propose, HITL, model, view loop without touching @braidhq/core or @braidhq/schema.
• Litmus test: grep -rn "'intent'\|'code'\|source-intent" packages/*/src packages/*/test hits only packages/ontology-ddd/**.
• ontology-ddd becomes a clean reference: it declares code / intent as data instead of relying on core knowing those names.

Invariants to keep

The HITL gate and the evidence / provenance rules stay. They are framework invariants, not part of the software-specific taxonomy. Only the source-role taxonomy is being lifted out.

Suggested staging

1. Open the type and the capability model. Schema role becomes a brand string, SDK gains sourceRoles, core de-hardcodes the four call sites, BatchInputMode renamed. DDD declares its two roles. Framework green.
2. End-to-end. Server unitScan and the roles endpoint, Studio driven by declared roles, skill-input provider generalized. A non-DDD ontology runs the full loop.
3. Evidence generalization, together with design: trust / convergence model for domains with no privileged fact-SSoT #68.

Related

• Plugin activation policy: how the server decides which registered plugins to load #51 plugin activation policy, which registered plugins the server loads.
• design: trust / convergence model for domains with no privileged fact-SSoT #68 trust / convergence model for domains with no privileged fact source, shares the stage-3 evidence work.

[mroops0111]

Review-pass finding: the extraction seam is clean, recording it so the eventual split is mechanical

Doing a review pass on @braidhq/server. Confirmed the kernel-vs-worldview split and where the coding worldview actually leaks. Keeping everything in @braidhq/server for now, since no second worldview exists yet and extraction would be speculative per this issue's forcing-function note. Recording the inventory so the split is mechanical when a story-world or research-notes app forces it.

Two distinct couplings, do not conflate

1. Package-dependency coupling, extract into @braidhq/preset-code.
Only ONE file imports the concrete plugin packages:

• packages/server/src/composeFsApp.ts, imports storage-kuzu, ontology-ddd, source-loader-{git,github,gdrive}, agent-claude-code.

So extraction is: move composeFsApp.ts plus those six dependencies out of packages/server/package.json into a new @braidhq/preset-code. composeApp.ts (the kernel root) already registers no plugin. Entries that run the coding app (server.ts via startServer, the cli serve command, desktop) then depend on @braidhq/preset-code instead of pulling plugins transitively through server. Default identities are already isolated as DEFAULT_* consts at the head of composeFsApp.ts.

2. SourceRole worldview leak, generalize in place, this is the core of this issue.
packages/schema/src/source.ts pins SourceRole = z.enum(['code','intent']). Hardcoded 'intent' / 'code' consumers that must become agnostic to ontology-declared roles:

• server: infrastructure/fs/intentScan.ts (source.role !== 'intent'), routes/skills.ts (s.role === 'intent').
  • routes/workspaces.ts already routes through the generic ontology.requiredSourceRoles / assertRequiredSourceRoles, no change, this is the pattern to extend.
• client: packages/studio/src/, 8 files hardcode the taxonomy through the schema enum (AddSourceDialog, CreateWorkspaceWizard, ActionInputForm, sourceDraft, api, Actions, Batch, MultiSelectDropdown). Studio has no plugin package dependency, but its source UI is worldview-coupled here. It must render whatever roles the active ontology declares.

Not coupled, stays kernel, reusable by a story or notes worldview as-is

routes, middleware, policy, tenancy, HITL, reactor, and infrastructure/{generic fs, git history, agent subprocess runner, auth, oauth, users, secrets}.

Forcing function to execute both: actually starting a second worldview app. Related: #51 tracks where composeFsApp's plugin bundle lives, which the package extraction above resolves.

[mroops0111]

Design note: a source has three orthogonal axes, not one

Surfaced while reviewing the source loaders and their webhook coupling. Recording it here because #50 re-cuts the source model, and these should be decided together rather than piecemeal.

A "source" currently squeezes three orthogonal concerns into loader kind + a hardcoded role:

Axis	What it decides	Host-specific?	Where it lives today
Fetch (loader)	how content is pulled: git clone, issues API, drive export	mostly no (git clone is universal)	plugin axis, already OCP for adding loaders
Host / provider	how a webhook delivery is verified + normalized (github HMAC, gitlab token)	yes	leaked: WebhookProvider = 'github' type + a github-only receiver in server
Role (code / intent)	what kind of knowledge the source is	no	hardcoded in the source descriptor; the Reactor gates on intent

Why not reorganize loaders by host

Tempting to drop the git package and split into source-loader-github / source-loader-gitlab that each own clone + issues + webhook. This is a bad trade:

• git clone / fetch / reset --hard is host-agnostic and works on hosts with no issues API and no webhook at all (self-hosted git, bitbucket, a bare git:// URL). A generic git-mirror loader must exist regardless.
• Organizing by host duplicates the entire mirror body per host; the only host-specific parts are URL parsing (owner/repo) and webhook verification (~10%).

So the right cut keeps one host-agnostic git-mirror loader, per-host issues loaders, and a host-level webhook verifier shared by any loader whose source lives on that host.

Webhook is two things, not one

• Dispatch decision ("is this delivery mine, should I sync") is a loader capability and already lives on the loader (repoIdentity + shouldDispatch).
• Verification (receive, check the host's HMAC, normalize the payload) is a host concern, shared across every loader on that host (git-on-github and github-issues use the same github verification). It should not live inside the git loader; GitLoader.parseGithubUrl returning provider: 'github' is the leak of the host axis into a protocol loader.

Naming

source-loader-github is really "github issues", not "github repos". Renaming to source-loader-github-issues removes the apparent overlap with the git-clone loader.

Recommendation

No package or webhook restructuring now (one host, one provider, YAGNI; the seam is already documented). When #50 re-cuts the source model, formalize the three axes together: fetch (host-agnostic loader), host (provider/webhook verification), role (ontology-declared). Strip the github knowledge out of the git loader at that point, not before.