@flowdular/sdk 0.1.0

package/.ai/blueprints/author-spec/input.schema.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["moduleId", "businessOutcome", "actors"],
+	"properties": {
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"businessOutcome": { "type": "string", "minLength": 20 },
+		"actors": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "type": "string", "minLength": 1 },
+			"uniqueItems": true
+		},
+		"constraints": { "type": "array", "items": { "type": "string" } }
+	}
+}

package/.ai/blueprints/author-spec/plan.schema.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["specPath", "openQuestions", "acceptanceScenarioCount"],
+	"properties": {
+		"specPath": {
+			"type": "string",
+			"pattern": "^modules/[a-z0-9-]+/spec/module\\.yaml$"
+		},
+		"openQuestions": { "type": "array", "items": { "type": "string" } },
+		"acceptanceScenarioCount": { "type": "integer", "minimum": 1 }
+	}
+}

package/.ai/blueprints/author-spec/required-files.yaml

@@ -0,0 +1,6 @@
+schemaVersion: 1
+create:
+  - modules/{module}/spec/module.yaml
+forbid:
+  - modules/{module}/src/**
+  - modules/{module}/module.json

package/.ai/blueprints/author-spec/spec-requirements.yaml

@@ -0,0 +1,35 @@
+schemaVersion: 1
+# Keys below exist in packages/contracts/schemas/module-spec.schema.json.
+status:
+  initial: draft
+  allowed:
+    - draft
+    - in-review
+  agentMayApprove: false
+requiredKeys:
+  - schemaVersion
+  - id
+  - specVersion
+  - status
+  - name
+  - description
+  - profile
+  - capabilities
+  - dependencies
+  - tenancy
+  - locales
+  - invariants
+  - permissions
+  - dataOwnership
+  - acceptanceScenarios
+identifiers:
+  id: ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$
+  permissions: <module>.<entity>.read and <module>.<entity>.manage
+  acceptanceScenarios: ^[A-Z][A-Z0-9-]+$
+acceptanceScenarios:
+  minimum: 3
+  mustInclude:
+    - denial
+    - tenant isolation
+openQuestions:
+  policy: stay in the handoff message; never guessed into the file

package/.ai/blueprints/author-spec/steps.yaml

@@ -0,0 +1,28 @@
+schemaVersion: 1
+steps:
+  - id: collect
+    role: business-manager
+    action: Validate the brief against input.schema.json (module id, outcome, actors); list the business facts still missing.
+    inputs: [brief]
+    outputs: [open questions]
+  - id: ask
+    role: business-manager
+    action: Stop and ask for every unresolved business or security decision instead of guessing.
+    inputs: [open questions]
+    outputs: [answers]
+  - id: draft
+    role: business-manager
+    action: Write spec/module.yaml from templates/module.yaml with status draft; permissions, invariants, dataOwnership, acceptanceScenarios complete.
+    inputs: [answers]
+    outputs: [spec/module.yaml]
+    gates: [spec-schema]
+  - id: validate
+    role: orchestrator
+    action: pnpm flowdular spec validate --all --json (the sandbox spec-schema gate).
+    inputs: [spec/module.yaml]
+    outputs: [gate evidence]
+  - id: handoff
+    role: business-manager
+    action: Leave status as draft or in-review; end with HANDOFF to backend-engineer (or ux-designer for a ui profile) and let the operator approve.
+    inputs: [spec/module.yaml]
+    outputs: [handoff line]

package/.ai/blueprints/author-spec/templates/module.yaml

@@ -0,0 +1,45 @@
+# Replace every {placeholder}. Keys are the ones module-spec.schema.json knows;
+# nothing else is accepted. Keep status: draft; a human approves.
+schemaVersion: 1
+id: '{moduleId}'
+specVersion: 0.1.0
+status: draft
+name: '{name}'
+description: '{businessOutcome}'
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: ^0.1.0
+  - id: auth.core
+    range: ^0.1.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Every {entity} is owned by exactly one tenant and every query uses the trusted tenant identifier.
+permissions:
+  - id: '{module}.{entities}.read'
+    description: Read {entities} in the active tenant.
+  - id: '{module}.{entities}.manage'
+    description: Create and update {entities} in the active tenant.
+dataOwnership:
+  - '{moduleId} owns {entity} identity and lifecycle status.'
+acceptanceScenarios:
+  - id: '{MODULE}-LIST'
+    given: Tenant-scoped {entities} exist.
+    when: An authorized principal lists {entities}.
+    then: Only {entities} owned by the active tenant are returned in deterministic order.
+  - id: '{MODULE}-CREATE'
+    given: An authorized principal supplies valid {entity} data.
+    when: The {entity} is created.
+    then: A tenant-owned active {entity} is persisted and returned with a generated identifier.
+  - id: '{MODULE}-DENY'
+    given: A principal is unauthenticated or lacks the required permission.
+    when: The principal reads or mutates {entities}.
+    then: The server denies the operation before repository access.

package/.ai/blueprints/bug-fix/README.md

@@ -0,0 +1,5 @@
+# bug-fix
+
+Fix a defect at the owning layer with a regression test that fails before the fix. In the sandbox this is an `edit-module` session whose brief describes a symptom; at the repository root it is `.ai/skills/bug-hunt/SKILL.md` followed by a pull request. A defect in `packages/**` switches to `core-extend` for the paths and gates, and keeps this blueprint's steps.
+
+No behaviour beyond the fix travels in the change: no refactors, no renames, no reformatting of untouched code.

package/.ai/blueprints/bug-fix/allowed-paths.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+write:
+  - modules/{module}/**
+deny:
+  - platform/**
+  - packages/**
+  - infra/**
+  - .github/**
+  - docs/**
+  - specs/**
+  - .ai/**
+  - flowdular.json
+  - pnpm-workspace.yaml
+  - modules/!({module})/**
+notes:
+  - a defect under packages/** follows core-extend allowed-paths.yaml
+# Written only by CLI commands, never by hand. The eject and the direct path
+# both run the commands; the files still travel in the same commit.
+cliOwned:
+  - path: flowdular.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/package.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/src/generated/modules.server.ts
+    command: pnpm flowdular module sync --apply
+  - path: platform/src/generated/modules.client.ts
+    command: pnpm flowdular module sync --apply
+  - path: pnpm-lock.yaml
+    command: pnpm install

package/.ai/blueprints/bug-fix/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "bug-fix",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": ["backend-engineer", "frontend-engineer", "module-executor"],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["reviewer"],
+	"requiresApprovedSpec": false
+}

package/.ai/blueprints/bug-fix/examples/invalid/input-no-symptom.json

@@ -0,0 +1,4 @@
+{
+	"scope": "module",
+	"target": "catalog.core"
+}

package/.ai/blueprints/bug-fix/examples/invalid/plan-no-test.json

@@ -0,0 +1,8 @@
+{
+	"blueprint": "bug-fix@1.0.0",
+	"rootCause": "A guess without reproduction.",
+	"owningLayer": "service",
+	"regressionTest": "",
+	"siblings": [],
+	"gates": ["typecheck"]
+}

package/.ai/blueprints/bug-fix/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"scope": "module",
+	"target": "catalog.core",
+	"symptom": "POST /api/catalog/items returns 500 when sku is longer than 64 characters.",
+	"reproduction": "createCatalogItem with a 70 character sku through route.handler(createContext(...))."
+}

package/.ai/blueprints/bug-fix/examples/valid/plan.json

@@ -0,0 +1,8 @@
+{
+	"blueprint": "bug-fix@1.0.0",
+	"rootCause": "requiredString max for sku is missing so the service throws a generic error after the HTTP layer accepted the value.",
+	"owningLayer": "http",
+	"regressionTest": "tests/module.test.ts: rejects a sku above 64 characters with INVALID_INPUT",
+	"siblings": ["modules/parties/src/api/endpoints.ts"],
+	"gates": ["typecheck", "tests", "format"]
+}

package/.ai/blueprints/bug-fix/gates.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+# Ids equal GateId in packages/sandbox/src/server/gates.ts. The sandbox runs the
+# gates a role lists in its front matter after every turn that changed files;
+# from the repository root run the command column yourself. Nothing executes
+# this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: module-schema
+    command: pnpm flowdular module validate --json
+    sandbox: pnpm flowdular module validate --json --root <session workspace>
+    required: true
+  - id: dependencies
+    command: 'grep the imports under src/** and compare with package.json dependencies (no CLI command yet)'
+    sandbox: checkDeclaredDependencies(modulePath) in packages/sandbox/src/server/dependencies.ts, run after every turn that changed files, plus a pnpm install when a package.json changed
+    required: true
+  - id: typecheck
+    command: pnpm --filter @flowdular/module-{module} typecheck
+    sandbox: node_modules/.bin/tsrx-tsc --noEmit -p tsconfig.json (cwd module)
+    required: true
+  - id: tests
+    command: pnpm --filter @flowdular/module-{module} test
+    sandbox: node_modules/.bin/vitest run --passWithNoTests (cwd module; zero tests still pass)
+    required: true
+  - id: format
+    command: pnpm format:check
+    sandbox: prettier --check . (cwd module)
+    required: true

package/.ai/blueprints/bug-fix/input.schema.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["scope", "target", "symptom"],
+	"properties": {
+		"scope": {
+			"type": "string",
+			"enum": ["module", "package"]
+		},
+		"target": {
+			"type": "string",
+			"minLength": 1
+		},
+		"symptom": {
+			"type": "string",
+			"minLength": 8,
+			"maxLength": 4000
+		},
+		"reproduction": {
+			"type": "string",
+			"maxLength": 4000
+		}
+	}
+}

package/.ai/blueprints/bug-fix/plan.schema.json

@@ -0,0 +1,53 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"blueprint",
+		"rootCause",
+		"owningLayer",
+		"regressionTest",
+		"siblings",
+		"gates"
+	],
+	"properties": {
+		"blueprint": {
+			"const": "bug-fix@1.0.0"
+		},
+		"rootCause": {
+			"type": "string",
+			"minLength": 8
+		},
+		"owningLayer": {
+			"type": "string",
+			"enum": ["http", "service", "repository", "client", "composition", "core"]
+		},
+		"regressionTest": {
+			"type": "string",
+			"minLength": 1
+		},
+		"siblings": {
+			"type": "array",
+			"items": {
+				"type": "string"
+			},
+			"uniqueItems": true
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"spec-schema",
+					"module-schema",
+					"dependencies",
+					"typecheck",
+					"tests",
+					"format"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/.ai/blueprints/bug-fix/required-files.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+required:
+  - tests/module.test.ts (or a new tests/*.test.ts) containing the regression test
+changed:
+  - exactly the files of the owning layer named in the plan
+forbidden:
+  - unrelated refactors, renames, reformatting of untouched code

package/.ai/blueprints/bug-fix/spec-requirements.yaml

@@ -0,0 +1,7 @@
+schemaVersion: 1
+status:
+  allowed:
+    - approved
+onFix:
+  specVersion: patch bump when the fix changes observable behaviour named in a scenario
+  acceptanceScenarios: add one only when the bug shows a missing scenario; never rewrite existing ones

package/.ai/blueprints/bug-fix/steps.yaml

@@ -0,0 +1,51 @@
+schemaVersion: 1
+steps:
+  - id: reproduce
+    role: backend-engineer
+    action: Write the failing test with the gate runner (vitest; route.handler(createContext(new Request(...), {})) or the service on the module's tests/support/database.ts provider).
+    inputs:
+      - 'symptom'
+      - 'reproduction'
+    outputs:
+      - 'tests/*.test.ts'
+    gates:
+      - 'tests'
+  - id: locate
+    role: backend-engineer
+    action: Map the symptom to the owning layer with the table in .ai/skills/bug-hunt/SKILL.md; state the root cause as input and state to wrong outcome.
+    inputs:
+      - 'failing test'
+    outputs:
+      - 'root cause'
+  - id: fix
+    role: backend-engineer
+    action: Smallest change in the owning file; no second guard in another layer.
+    inputs:
+      - 'root cause'
+    outputs:
+      - 'owning file'
+    gates:
+      - 'typecheck'
+      - 'tests'
+      - 'format'
+  - id: siblings
+    role: backend-engineer
+    action: grep the same pattern across modules/*/src and either fix or list the siblings.
+    inputs:
+      - 'pattern'
+    outputs:
+      - 'siblings list'
+  - id: land
+    role: orchestrator
+    action: 'Sandbox: eject. Direct path: pnpm verify, pull request with the root cause and the regression test name.'
+    inputs:
+      - 'diff'
+    outputs:
+      - 'pull request'
+    gates:
+      - 'spec-schema'
+      - 'module-schema'
+      - 'dependencies'
+      - 'typecheck'
+      - 'tests'
+      - 'format'

package/.ai/blueprints/core-extend/README.md

@@ -0,0 +1,5 @@
+# core-extend
+
+Change a platform package (`packages/**`, `platform/**`, the schemas in `packages/contracts`, or the auth server contract in `modules/auth/src/server/composition.ts`). This runs at the repository root only; a sandbox session cannot reach these paths and hands off with the exact change needed. Procedure and checklists: `.ai/skills/core-extend/SKILL.md`.
+
+Every public surface change names and migrates its consumers in the same change (modules, scaffold, generated composition, reference copies for sandbox sessions, docs, skills). Gates are the repository gates: `pnpm verify` and `pnpm build`. A change to a public boundary gets an ADR in `docs/adr`.

package/.ai/blueprints/core-extend/allowed-paths.yaml

@@ -0,0 +1,49 @@
+schemaVersion: 1
+write:
+  - packages/**
+  - platform/octane.config.ts
+  - platform/src/**
+  - platform/scripts/**
+  - modules/auth/src/server/composition.ts
+  - modules/*/module.json
+  - modules/*/spec/module.yaml
+  - modules/*/src/platform.ts
+  - docs/**
+  - .ai/**
+  - .agents/skills/**
+  - .claude/skills/**
+  - AGENTS.md
+  - CLAUDE.md
+  - rulesync.jsonc
+  - package.json
+  - pnpm-workspace.yaml
+deny:
+  - platform/src/generated/**
+  - flowdular.json
+  - infra/**
+  - .github/**
+  - pnpm-lock.yaml (only through pnpm install)
+notes:
+  - modules/** beyond the listed files belong to edit-module; a consumer migration touches only the lines the contract change forces
+  - AGENTS.md, CLAUDE.md, .agents/skills and .claude/skills are written only by pnpm rules:generate
+# Written only by CLI commands, never by hand. The eject and the direct path
+# both run the commands; the files still travel in the same commit.
+cliOwned:
+  - path: flowdular.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/package.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/src/generated/modules.server.ts
+    command: pnpm flowdular module sync --apply
+  - path: platform/src/generated/modules.client.ts
+    command: pnpm flowdular module sync --apply
+  - path: pnpm-lock.yaml
+    command: pnpm install
+  - path: AGENTS.md
+    command: pnpm rules:generate
+  - path: CLAUDE.md
+    command: pnpm rules:generate
+  - path: .agents/skills
+    command: pnpm rules:generate
+  - path: .claude/skills
+    command: pnpm rules:generate

package/.ai/blueprints/core-extend/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "core-extend",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": ["module-executor"],
+	"executorProfiles": ["repo-agent"],
+	"requiredReviewers": ["reviewer", "platform-owner"],
+	"requiresApprovedSpec": false
+}

package/.ai/blueprints/core-extend/examples/invalid/input-unknown-package.json

@@ -0,0 +1,5 @@
+{
+	"package": "@flowdular/module-catalog",
+	"change": "server-contract",
+	"brief": "Change a business module through the core blueprint."
+}

package/.ai/blueprints/core-extend/examples/invalid/plan-missing-gates.json

@@ -0,0 +1,7 @@
+{
+	"blueprint": "core-extend@1.0.0",
+	"package": "@flowdular/server",
+	"consumersMigrated": [],
+	"adr": false,
+	"gates": []
+}

package/.ai/blueprints/core-extend/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"package": "@flowdular/module-auth",
+	"change": "server-contract",
+	"brief": "Add an optional agentTools list to PlatformServerComposition.",
+	"consumers": ["modules/*/src/platform.ts", "packages/cli/src/module-sync.ts"]
+}

package/.ai/blueprints/core-extend/examples/valid/plan.json

@@ -0,0 +1,10 @@
+{
+	"blueprint": "core-extend@1.0.0",
+	"package": "@flowdular/module-auth",
+	"consumersMigrated": [
+		"modules/agents/src/platform.ts",
+		"packages/cli/src/module-sync.ts"
+	],
+	"adr": true,
+	"gates": ["pnpm verify", "pnpm build"]
+}

package/.ai/blueprints/core-extend/gates.yaml

@@ -0,0 +1,16 @@
+schemaVersion: 1
+# Repository gates. Nothing executes this file; CI runs the same commands
+# (.github/workflows/ci.yml).
+gates:
+  - id: verify
+    command: pnpm verify
+    required: true
+  - id: build
+    command: pnpm build
+    required: true
+  - id: platform-typecheck
+    command: pnpm --filter @flowdular/platform typecheck
+    required: true
+  - id: audit
+    command: pnpm audit --prod --audit-level high
+    required: false

package/.ai/blueprints/core-extend/input.schema.json

@@ -0,0 +1,54 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["package", "change", "brief"],
+	"properties": {
+		"package": {
+			"type": "string",
+			"enum": [
+				"@flowdular/contracts",
+				"@flowdular/kernel",
+				"@flowdular/server",
+				"@flowdular/client",
+				"@flowdular/ui",
+				"@flowdular/cli",
+				"@flowdular/cli-protocol",
+				"@flowdular/sandbox",
+				"@flowdular/coding-agent",
+				"@flowdular/harness",
+				"@flowdular/ai-provider",
+				"@flowdular/dev-console",
+				"@flowdular/platform",
+				"@flowdular/module-auth"
+			]
+		},
+		"change": {
+			"type": "string",
+			"enum": [
+				"schema",
+				"server-contract",
+				"client-contract",
+				"ui-primitive",
+				"cli",
+				"sandbox",
+				"coding-agent",
+				"kernel",
+				"composition"
+			]
+		},
+		"brief": {
+			"type": "string",
+			"minLength": 8,
+			"maxLength": 20000
+		},
+		"consumers": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/.ai/blueprints/core-extend/plan.schema.json

@@ -0,0 +1,39 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["blueprint", "package", "consumersMigrated", "adr", "gates"],
+	"properties": {
+		"blueprint": {
+			"const": "core-extend@1.0.0"
+		},
+		"package": {
+			"type": "string",
+			"pattern": "^@flowdular/[a-z-]+$"
+		},
+		"consumersMigrated": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"uniqueItems": true
+		},
+		"adr": {
+			"type": "boolean"
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"pnpm verify",
+					"pnpm build",
+					"pnpm --filter @flowdular/platform typecheck"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}