Skip to content

Guided tour

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

MODULE 07 · LESSON 7.4

Extend blueprints for your own product

Add your own blueprint extension without breaking other consumers.

Lesson 42 of 86 · FabrCore 2.0

Overview

A product may need to expand one business definition into several agents. IBlueprintExpander keeps that logic server-side; a preview-capable extension provides the same configuration calculation without creating agents or contacting external services.

Keep the canonical envelope reusable

Your product can add a namespaced, versioned extension for a business concept while retaining the standard blueprint fields. An expander translates that extension into ordinary runtime definitions. This lets clients store and move the document without knowing every product-specific rule, provided they preserve fields they do not understand.

Preview must be free of business effects

An expander used for review should describe what would be created without provisioning agents, calling a paid service or writing a business record. The effect-free preview contract makes revision/digest review meaningful. If expansion changes for identical inputs, a reviewer cannot reliably compare the displayed plan with the eventual deployment.

Add a product-owned blueprint extension

  1. Define a namespaced top-level extension with a versioned schema. Validate required fields and principal scope.
  2. Implement IBlueprintExpander and the supported preview contract, register them through DI, and preserve unrelated extensions during round-trip editing.
  3. Test expansion deterministically, then compare preview and apply on the same input/revision. Keep consent and token acquisition out of preview.
blueprints.md · reference snippet 
POST /fabrcoreapi/Agent/blueprint
x-user-handle: developer1
Content-Type: application/json
blueprints.md · reference snippet 
{
  "FabrCore": {
    "AdminAuthentication": {
      "ApiKey": "<secret>",
      "PrincipalId": "forge-cluster-admin"
    }
  }
}

Round-trip and preview the extension

  1. Add a small versioned extension to a test blueprint and export/import it through your editor. Compare the extension JSON before and after; unknown fields should remain intact.
  2. Preview the same document twice and compare the expanded targets/digest. No runtime agents or external effects should appear merely from previewing.
  3. Apply the reviewed definition and verify the actual instances match the preview. Reject unsupported extension versions with a clear error instead of silently dropping their behavior.

This establishes a portable definition and a trustworthy review boundary. Custom product behavior remains explicit rather than hidden in a deployment side effect.

If the result is different

Do not perform external effects inside preview. Unknown extension data must not disappear during an agents-only import/export path.

Go deeper

Explore the related documentation.