Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/wordpress-crud-db-contracts.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# WordPress CRUD and DB Operation Contracts

WP Codebox exposes two generic WordPress operation commands for runtimes that need bounded WordPress state access without product-specific adapters.
WP Codebox exposes two generic WordPress operation commands for runtimes that need WordPress state access without product-specific adapters.

## `wordpress.crud-operation`

Expand All @@ -18,9 +18,9 @@ Supported resource kinds in the Playground backend:

Write guardrails:

- `create`, `update`, and `delete` require `options.allowWrites=true`.
- `create`, `update`, and `delete` require `options.destructivePermission=true` inside an explicit disposable sandbox boundary.
- `options.dryRun=true` validates and returns planned effects without applying writes.
- Missing write approval returns `status=error` with `write-guard-required`.
- Missing destructive permission returns `status=error` with `destructive-permission-required`.

## `wordpress.db-operation`

Expand All @@ -35,8 +35,8 @@ Foundational supported operations:

DB write guardrails:

- `write` returns `status=error` with `db-write-unsupported`.
- Generic DB writes are intentionally not implemented; callers should use `wordpress.crud-operation` with explicit write approval for bounded WordPress core API writes.
- `write` requires `options.destructivePermission=true` inside an explicit disposable sandbox boundary.
- Missing destructive permission returns `status=error` with `db-destructive-permission-required`.

Read guardrails:

Expand Down
10 changes: 5 additions & 5 deletions packages/runtime-core/src/command-registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -666,12 +666,12 @@ export const commandRegistry = [
acceptedArgs: [
{ name: "operation-json", description: "Inline wp-codebox/wordpress-crud-operation/v1 operation envelope. The runtime normalizes schema, operation, resource, data, query, options, and metadata fields before execution.", required: true, format: "JSON object" },
],
outputShape: "wp-codebox/wordpress-crud-result/v1 JSON with command, status, normalized operation, optional item/items, effects, diagnostics, errors, artifactRefs, and metadata. Writes require options.allowWrites=true or return status=error without applying effects; dry runs return planned effects only.",
outputShape: "wp-codebox/wordpress-crud-result/v1 JSON with command, status, normalized operation, optional item/items, effects, diagnostics, errors, artifactRefs, and metadata. Writes require options.destructivePermission=true inside an explicit disposable sandbox boundary or return status=error without applying effects; dry runs return planned effects only.",
outputSchema: {
id: WORDPRESS_CRUD_RESULT_SCHEMA,
jsonSchema: WORDPRESS_CRUD_RESULT_JSON_SCHEMA,
},
policyRequirement: "Runtime policy commands must include wordpress.crud-operation. Backend implementations must fail closed for writes unless options.allowWrites=true or options.dryRun=true.",
policyRequirement: "Runtime policy commands must include wordpress.crud-operation. Backend implementations must fail closed for writes unless options.destructivePermission=true or options.dryRun=true.",
recipe: true,
handler: { kind: "playground", method: "runCrudOperation" },
},
Expand Down Expand Up @@ -710,16 +710,16 @@ export const commandRegistry = [
},
{
id: "wordpress.db-operation",
description: "Execute a bounded generic WordPress database operation envelope for schema/table inspection, safe reads, and query summaries across discovered prefixed WordPress tables. Generic writes are explicitly rejected by the foundational contract.",
description: "Execute a generic WordPress database operation envelope for schema/table inspection, safe reads, query summaries, and explicitly permitted destructive writes inside a disposable sandbox boundary.",
acceptedArgs: [
{ name: "operation-json", description: "Inline wp-codebox/wordpress-db-operation/v1 operation envelope. Supports schema, read, inspect, query-summary, and guarded write operations. Reads and inspections require a discovered prefixed table and described table columns.", required: true, format: "JSON object" },
],
outputShape: "wp-codebox/wordpress-db-result/v1 JSON with command, status, normalized operation, optional item/items, diagnostics, errors, artifactRefs, and metadata. Schema results classify tables as core, prefixed, or external where observable and may include bounded columns, indexes, and status metadata. Generic DB writes return status=error with db-write-unsupported.",
outputShape: "wp-codebox/wordpress-db-result/v1 JSON with command, status, normalized operation, optional item/items, diagnostics, errors, artifactRefs, and metadata. Schema results classify tables as core, prefixed, or external where observable and may include bounded columns, indexes, and status metadata. DB writes require options.destructivePermission=true inside an explicit disposable sandbox boundary.",
outputSchema: {
id: WORDPRESS_DB_RESULT_SCHEMA,
jsonSchema: WORDPRESS_DB_RESULT_JSON_SCHEMA,
},
policyRequirement: "Runtime policy commands must include wordpress.db-operation. DB reads are bounded to discovered prefixed WordPress tables, allowlisted to described columns, and capped row counts; generic writes are rejected.",
policyRequirement: "Runtime policy commands must include wordpress.db-operation. DB reads are bounded to discovered prefixed WordPress tables, allowlisted to described columns, and capped row counts; writes require an explicit disposable sandbox destructive permission.",
recipe: true,
handler: { kind: "playground", method: "runDbOperation" },
},
Expand Down
10 changes: 5 additions & 5 deletions packages/runtime-core/src/fuzz-suite-runner.ts
Original file line number Diff line number Diff line change
Expand Up @@ -841,11 +841,11 @@ function runtimeActionFuzzSuiteTargetAdapter(): FuzzSuiteTargetAdapter {
if (input.payload.type === "db_operation") {
try {
const rawOperation = normalizeWordPressDbOperation({ schema: WORDPRESS_DB_OPERATION_SCHEMA, ...input.payload, operation: input.payload.operation ?? "read" })
const resetPolicyAllowsMutation = rawOperation.operation === "write" ? fuzzSuiteResetPolicyAllowsMutation(suite, fuzzCase) : undefined
const operation = resetPolicyAllowsMutation ? normalizeWordPressDbOperation({
const disposableSandboxBoundary = rawOperation.operation === "write" ? fuzzSuiteDisposableSandboxBoundary(suite) : undefined
const operation = disposableSandboxBoundary ? normalizeWordPressDbOperation({
...rawOperation,
options: { ...(rawOperation.options ?? {}), allowWrites: true, resetIsolated: true },
metadata: { ...(rawOperation.metadata ?? {}), resetIsolated: true, affectedRowsMayBeZeroOrUnknown: true },
options: { ...(rawOperation.options ?? {}), destructivePermission: true },
metadata: { ...(rawOperation.metadata ?? {}), disposableSandboxBoundary, affectedRowsMayBeZeroOrUnknown: true },
}) : rawOperation
return {
status: "supported",
Expand All @@ -854,7 +854,7 @@ function runtimeActionFuzzSuiteTargetAdapter(): FuzzSuiteTargetAdapter {
args: [`operation-json=${JSON.stringify(operation)}`],
timeoutMs: runtimeActionTimeoutMs(input.payload, input.timeoutMs),
}) as ExecutionSpec,
metadata: stripUndefined({ adapterKind: "runtime-action", actionType: input.payload.type, mappedCommand: "wordpress.db-operation", resetPolicyAllowsMutation }),
metadata: stripUndefined({ adapterKind: "runtime-action", actionType: input.payload.type, mappedCommand: "wordpress.db-operation", disposableSandboxBoundary }),
}
} catch (error) {
return unsupportedInputAdapterResolution(fuzzCase, target, error instanceof Error ? error.message : String(error), { adapterKind: "runtime-action", actionType: input.payload.type })
Expand Down
27 changes: 27 additions & 0 deletions packages/runtime-core/src/mutation-isolation-contracts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ export interface MutationIsolationArtifact {
target: string
method: string
status?: number
sandboxBoundary?: DisposableDestructiveSandboxBoundaryEvidence
destructivePermission?: true
mutationBoundary?: MutationBoundaryEvidence
teardown?: DisposableSandboxTeardownEvidence
checkpointName?: string
beforeCheckpoint?: MutationIsolationStepEvidence
afterObservation?: MutationIsolationStepEvidence
Expand All @@ -32,6 +36,29 @@ export interface MutationIsolationArtifact {
metadata?: Record<string, unknown>
}

export interface DisposableDestructiveSandboxBoundaryEvidence {
disposable: true
destructivePermission: true
teardown: "discard" | "destroy" | (string & {})
backend?: string
environment?: string
hostAccess?: "declared-mounts-only" | (string & {})
metadata?: Record<string, unknown>
}

export interface MutationBoundaryEvidence {
permission: "destructive"
containment: "disposable-sandbox"
artifactEvidence: "captured"
}

export interface DisposableSandboxTeardownEvidence {
intent: "discard" | "destroy"
status: "intended" | "discarded" | "destroyed" | (string & {})
evidence?: string
metadata?: Record<string, unknown>
}

export interface DeleteBoundaryArtifact extends Omit<MutationIsolationArtifact, "schema" | "artifactKind"> {
schema: typeof DELETE_BOUNDARY_ARTIFACT_SCHEMA
artifactKind: typeof DELETE_BOUNDARY_ARTIFACT_KIND
Expand Down
Loading