Plugin check: Run
node "${PLUGIN_ROOT}/scripts/check-version.js"- if it outputs a message, show it to the user before proceeding.
📋 Shared instructions: shared-instructions.md — read first.
Add Dataverse
App root: before any project read or command, execute
app-working-directory.md.
Use its resolved absolute working_dir for every shell call and file tool,
including referenced commands and delegated skills; never inherit a prior cd.
Entry routing: use the shared App feature entry points preflight before the workflow below.
Invocation scope: follow Data-source invocation scope before the workflow below. Standalone calls use this skill's own data-delta approval and verification; do not start a full-app plan or screen workflow.
An existing plan alone does not mean it includes or approves the new request; never replay the old Data Model instead of resolving the requested delta.
Removal branch: after resolving invocation scope, --remove or an approved app-binding
removal executes
data-source-removal.md, then
returns without entering Steps 1-9. Removing a plan row is not implemented by
re-running table creation or by deleting Dataverse metadata. For a mixed edit,
the owner adds/refreshes first and invokes removal separately after consumer edits.
Refresh branch: after resolving invocation scope, --refresh or an approved service-only
refresh executes Refresh a retained source
and returns before Steps 1-9. Preserve the exact --data-source-name and approved
binding identity. Do not replay schema writes, publish, or run add-data-source.
Two paths:
- Existing tables only — resolve the current scope in Steps 1–2, then skip schema writes and use Step 6 to add only missing approved bindings or refresh approved retained sources.
- New / extended tables — full workflow with Web API mutations in dependency order
Workflow
- Verify project & auth → 2. Resolve plan/operation manifest → 3. Setup Dataverse Web API auth → 4. Validate manifest or reconcile live metadata → 5. Execute sequential metadata phases → 6. Add data sources → 6b. Publish fallback customizations → 6c. Verify tables → 6d. Write manifest → 7. Inspect generated files → 8. Type-check → 8.5. Offline profile reconciliation → 9. Summary
Step 1 — Verify project & auth
Confirm Power Apps mobile app:
For --plan-only or a planning-phase handoff, check the app files read-only and
use the shared proposal-only environment-context rule. Use the same non-persisting
lookup before approval in a normal invocation. Incomplete or conflicting context
returns NEEDS_CONTEXT after read-only recovery; never remove the safety flags
or redirect output into configuration to make planning succeed.
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
if [ ! -f power.config.json ] || [ ! -f app.config.js ]; then
echo "BLOCKED: working_dir is not an initialized app" >&2
exit 1
fi
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "<selected-environment-id>" --no-cache --require-tenant
Read <selected-environment-id> from this app's power.config.json. Capture the
environment URL (for example https://contoso.crm.dynamics.com),
environment ID, and tenant ID from the resolver for Step 3. Use the
owner's absolute working_dir for every command and artifact.
Step 2 — Resolve plan
Telemetry checkpoint: resolve_dataverse_schema_plan
Look for native-app-plan.md in the project root:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f native-app-plan.md
Resolve the current request before consuming an existing plan. A direct
standalone invocation must compare its requested tables/columns/service
changes with the existing plan and read-only live evidence. Present and approve
that exact delta at Step 2.7 after shared planning validation, then save only
the accepted plan changes before implementation.
If the request adds nothing, verify the existing outcome and report a no-op;
do not apply other pending rows. If intent or scope is missing, ask or return
NEEDS_CONTEXT without mutation. An explicit request to apply the whole existing
plan still requires approval of the reconciled operation set.
For an approved child call, use only the supplied current approved_scope.
In either case, --plan-only returns the proposal and STOPs before plan saving,
approval-receipt creation, service generation, or Steps 3–9; a planning-phase
caller has the same proposal-only boundary.
Before reading plan content, inspect $ARGUMENTS for the five fast-path
artifact flags in Step 2a. When all are present, only confirm
native-app-plan.md exists for hash validation; do not parse its Data Model
section or build operations/service lists from Markdown.
For all non-fast-path Dataverse proposals from /setup-datamodel, /edit-app, or
a standalone request, including an existing-plan delta, read and execute
dataverse-change-planning.md.
Use its scoped evidence/contract for the diagram, architect, or inline path.
An approved child with planning_snapshot, architect_evidence, and
schema_contract instead enters Step 2b to verify that supplied scope; it must
not rediscover or re-approve it. New-binding requests use this planning path;
service-only refreshes and retirements have already returned from their branches.
Older callers may not supply the new structured handoff. Do not assume compact
evidence or complete approval from the caller's name. Without a complete approved
handoff, resolve the current requested delta and use this leaf's normal proposal
and Step 2.7 approval path before execution. Resolve required invocation context
first; a missing or conflicting child root still returns NEEDS_CONTEXT before
project access. Never silently replay the saved plan or treat --skip-planning
as consent.
An approved legacy child without compact-planning artifacts keeps the supported Markdown/live-reconciliation path below only when its current request, absolute root, implementation phase, and exact approved delta are all established. Never use this legacy path to bypass a partial or invalid compact-planning handoff, or to skip setup/standalone proposal validation.
Legacy input only, if present and <operation_manifest_mode> = fallback
without a shared scoped contract: read the
## Data Model section. Extract:
- The target reconciliation table (
reuse/extend/create/adapt/deferdecisions and evidence) - The Mermaid ER diagram (informational)
- The "Creation Order" tier list
- Every table referenced by
## Screens, identity resolution, related-entity fields, forms, dashboards, or shared hooks, including standard reused tables such assystemuser,contact, andaccount
For legacy callers without scoped planning artifacts, build
SERVICE_REQUIRED_TABLES as the union of:
- every non-deferred row in Target Reconciliation (
reuse,extend,create, oradapt); - every table in Creation Order;
- every table named by screen/hook data requirements.
Keep this full service inventory as retained context. Only the current approved delta and its necessary dependencies enter live schema reconciliation. With a complete approved legacy handoff, proceed to Step 3 after this initialization; do not repeat proposal Steps 2.5–2.7 or require new compact artifacts from that owner. A planning-phase caller still returns without implementation.
For the shared scoped path, use the normalized contract's non-deferred
serviceRequired declarations instead. Keep the broader existing-app service
inventory as retained context, not a registration or mutation work list.
Hard rule: reuse means "do not mutate schema"; it does not mean "skip generated service." If app code reads or writes a reused table, that table must be in SERVICE_REQUIRED_TABLES.
Carry forward any adapt (auto-renamed) and defer (out-of-scope this run) decisions with their recorded reasons, and apply the alias map to every name you use. A data-modelling conflict never halts this skill — it resolves to adapt or defer and is reported in Step 9.
This classification belongs to planning: after approval, a changed decision
returns to the owner for revision/approval before any write.
For a scoped handoff, restrict schema writes to the exact approved_scope delta;
unaffected plan rows are context, not permission to replay their mutations.
Apply the same restriction to the newly approved standalone request delta.
Retain the full required-service set for existing screens. If reconciliation
would change an approved name, storage target, or screen contract, return the
proposed adaptation to the owner (or standalone user) before writing. Report
dependent consumer changes for separate approval; do not silently rename
underneath the app or treat data approval as permission to edit screens.
If absent: check $ARGUMENTS for diagram hints (*.png, *.jpg, *.jpeg filename, erDiagram keyword, ||--o{ cardinality syntax).
Diagram hint present → Path A (Step 2.5).
No hint AND
$ARGUMENTSdescribes what the app does (the typical case) → silently take Path B (Step 2.6 — spawn architect). No prompt.No hint AND
$ARGUMENTSis empty / non-descriptive → only then prompt withAskUserQuestion:"How would you like to define the data model? (a) I have an existing ER diagram to upload (PNG/JPG path, Mermaid syntax, or text description) (b) Let the data-model-architect agent analyze and propose one (default) (c) Cancel — I'll plan it elsewhere first"
Recommend (b), but wait for an explicit answer. Empty input is not approval; cancellation stops the workflow without planning or mutation. A supplied description may select the read-only architect path, not approve its result.
With an existing plan and a new request, take the same diagram or architect/ inline proposal path for only that delta, then Step 2.7. Do not skip validation because a saved plan exists.
Step 2a — Approved operation-manifest fast path
When $ARGUMENTS supplies all five paths below, record
<operation_manifest_mode> = candidate:
--schema-contract <working_dir>/.tmp/dataverse-schema-contract.json--approval-receipt <working_dir>/.tmp/mobile-plan-status.json--execution-reconciliation <working_dir>/.tmp/dataverse-execution-reconciliation.json--operation-manifest <working_dir>/.tmp/dataverse-operation-manifest.json--publish-checkpoint <working_dir>/.tmp/dataverse-publish-pending.json
Do not reconstruct tables, columns, relationships, keys, payloads, tiers, or
service requirements from Markdown on this path. The gate-owned approval receipt binds
the exact structured contract content/hash, final plan hash, and final
screen/service dependency list; native-app-plan.md remains the human review
artifact.
An entirely absent fast-path handoff means
<operation_manifest_mode> = fallback and preserves the standalone workflow
below, beginning with Step 2 initialization. A partially supplied handoff, or
a supplied manifest/contract/reconciliation/checkpoint that is malformed, stale,
incomplete, or bound to different context/files, must fail closed: print the
exact validation errors and return control to the orchestrator. Never jump to
Step 4 without Step 2 initialization, partially trust a candidate, or mix its
operations with agent-derived operations.
For an approved implementation candidate, continue to Step 3 and the existing
Step 3c manifest validation; skip Steps 2b and 2.5–2.7. Supplied execution
artifacts never override --plan-only or a planning-phase caller: those calls
return the proposal without entering Step 3.
Step 2b — Approved scoped planning context
Enter only for a shared compact-planning handoff, not an approved legacy child
or a creation fast-path candidate. The data owner passes the
absolute planning_snapshot, architect_evidence, and schema_contract paths
plus accepted operations, contract_sha256, and plan_sha256 in
approved_scope. Require all fields and real implementation approval;
partial, missing, changed, or mismatched context returns NEEDS_CONTEXT to
the owner, never a fallback to whole-plan replay or fresh approval inference.
Before Step 3, compare SHA-256 of the contract and final plan file bytes with those frozen approval hashes, verify the selected target identity, and run the shared compact-evidence and decision validators against the supplied artifacts. Do not overwrite either hash to accept changed files. Read mutation intent from the normalized scoped contract, not historical Markdown rows; retain unaffected generated services. A proposal-only caller returns without mutation.
After success, keep <operation_manifest_mode> = fallback for the existing
standalone execution/reconciliation path, skip Steps 2.5–2.7, and proceed to
Step 3. Planning evidence is not fresh write evidence: Step 4 still reconciles
only this accepted delta and its required dependencies against the live target.
Do not fabricate a create-mobile-app receipt or partially supply Step 2a flags.
Step 2.5 — Path A: Parse user-provided diagram
Used when the user has an existing diagram from another tool (Visio, dbdiagram.io, screenshot, hand-drawn).
Accept three input formats:
| Format | How |
|---|---|
Image path (*.png / *.jpg / *.jpeg) |
Use Read on the file path. The vision-capable model extracts entities, columns, relationships. |
| Mermaid syntax | User pastes a erDiagram block in chat. Parse the entities, columns, and ||--o{ cardinalities directly. |
| Text description | Parse the requested entities/relationships as intent, then use the shared snapshot-only architect handoff with the text and scoped compact evidence. |
Whichever format, normalize into the same structure used by the planner agent:
publisherPrefix: <from detected publisher prefix or user>
tables:
- logicalName: contoso_servicevisit
displayName: Service Visit
status: new # new | extend | reuse
columns: [...]
relationships: [...]
Then follow the shared planning workflow to generate _dm_section.md with
the Mermaid diagram and a normalized .tmp/dataverse-schema-contract.json
from compact evidence. Run its decision validation for the diagram just as for
an architect result, then continue to Step 2.7. Do not save the live plan here.
Step 2.6 — Path B: Spawn architect agent
If the user picked Path B, use the shared workflow's
mobile-app:data-model-architect handoff with Dataverse planning mode: required,
the absolute snapshot/compact-evidence paths, the scoped request, and planning/
proposal-only context. Require _dm_section.md and the normalized contract.
If the host cannot spawn agents, produce both inline from that same evidence.
Use the shared structured-signal recovery before generic retries. A diagram
parse failure requires resolving the intended entities, not silently inventing
a replacement model.
If they need new tables and refuse both paths, recommend /setup-datamodel for
data-only planning and stop. Do not start another workflow without a new request.
Step 2.7 — Validate and approve the standalone delta
For every new standalone proposal, require exit 0 from
validate-dataverse-planning-decisions.js for the current normalized contract
and snapshot before presenting the existing approval gate. This includes
diagrams, architect results, inline fallbacks, and edits to an existing plan.
If either --plan-only or a planning-phase caller applies, return the validated
proposal and STOP before saving the live plan or granting execution permission.
Otherwise show the exact delta and its concerns with EnterPlanMode. Approval
saves only that delta into native-app-plan.md, preserving unaffected sections.
Freeze the shared planning paths, accepted operations, and current
contract_sha256 / plan_sha256 as this invocation's approved context; verify
it using Step 2b before implementation. Revision repeats planning validation;
cancellation stops without saving or mutation. Already-approved scoped child
calls and valid creation fast-path calls do not repeat this gate.
Step 3 — Setup Dataverse Web API auth
Required only after implementation approval. For approved existing-table bindings with no schema mutation, skip to Step 6, not the schema-write phases.
Step 3a — Environment consistency check
The Power Apps CLI ($PA) and az authenticate independently — they can point to different accounts. Verify power.config.json resolves and az can token for the target tenant before making any Dataverse API calls:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
ENVIRONMENT_ID=$(node -p "require('./power.config.json').environmentId") || exit 1
ENV_JSON=$(node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$ENVIRONMENT_ID") || exit 1
echo "$ENV_JSON"
az account show --query "{user: user.name, tenant: tenantId}" -o json
Compare the resolved environment URL with <envUrl> captured in Step 1. If they differ, STOP and warn:
"⚠️ Environment mismatch detected:
- resolver reports:
<resolved_env_url>- This project targets:
<envUrl>The Dataverse API token comes from
az, which must target the same tenant as the selected environment. Run:cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } az login --tenant <tenant-id> # switch az to the right tenantThen re-run
/add-dataverse."
Do NOT proceed with table creation if environments don't match — you'll create tables in the wrong org.
Step 3b — Acquire token
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
az account show --query "user.name" -o tsv
If empty, instruct az login and stop.
Script invocation contract — read this once, all subsequent calls in this skill follow it:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> <METHOD> <apiPath> \
[--body '<json>'] [--include-headers] \
--tenant-id '<tenantId-from-resolve-environment>'
- Three positional args, in order:
<envUrl>,<METHOD>(GET / POST / PATCH / DELETE),<apiPath>(everything after/api/data/v9.2/). - Body is a flag, not positional.
--body '<json>'— required for POST/PATCH, never for GET/DELETE. Forgetting--bodyand passing the JSON as a 4th positional arg returns a usage error. --include-headersadds response headers (needed forOData-EntityIdafter a record create).- Output is JSON:
{ "status": <code>, "data": <body> }. Token refresh on 401 and back-off on 429 are automatic — never wrap with manual retry.
Pass the resolved tenant explicitly (HARD — saves discovery and survives fresh shells). resolve-environment.js already returned tenantId in Step 1. Substitute that literal value into every --tenant-id argument; do not rely on an exported or shell-local variable because separate tool executions may use fresh shells.
If the tenant is unknown, omit --tenant-id — discovery still works, it is just slower.
Acquire a Dataverse access token and verify connectivity:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET WhoAmI \
--tenant-id '<tenantId-from-resolve-environment>'
The explicit tenant is also reused for token refresh after a 401 and takes priority over shell environment variables and Azure account discovery.
WhoAmI is the Dataverse identity endpoint — capital W/A/I (case-sensitive). The response gives UserId, BusinessUnitId, OrganizationId but does NOT include the publisher prefix. To get the publisher prefix, query the solution's publisher (defaults to Default; pass a different solution name if the env uses a custom solution):
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/detect-publisher-prefix.js" <envUrl> [solutionName] \
--tenant-id '<tenantId-from-resolve-environment>'
# solutionName defaults to "Default" if omitted
This runs the OData query:
/api/data/v9.2/solutions?$select=uniquename&$expand=publisherid($select=customizationprefix)&$filter=uniquename eq '<solutionName>'
Capture customizationprefix from the solution's publisher (typical value: cr123 → schema names like cr123_jobsite). Also capture the solution uniquename — needed for the --solution flag on every Step 5 / 5b POST so artifacts land in our solution rather than landing wherever Dataverse defaults. Write both to memory-bank.md Power Platform context block.
Requires the user to hold System Administrator or System Customizer in this environment.
When <operation_manifest_mode> = candidate, validate the manifest now against
the resolved environment, tenant (when available), publisher, solution, current
plan bytes, structured-schema bytes, and fresh reconciliation bytes:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/build-dataverse-operation-manifest.js" \
--validate '<operation-manifest-path>' \
--contract '<schema-contract-path>' \
--approval-receipt '<approval-receipt-path>' \
--reconciliation '<execution-reconciliation-path>' \
--plan '<working_dir>/native-app-plan.md' \
--environment-id "<environmentId>" \
--env-url "<envUrl>" \
--tenant-id "<tenantId>" \
--publisher-prefix "<customizationprefix>" \
--solution "<solution-uniquename>" \
--publish-checkpoint '<publish-checkpoint-path>' \
--require-executable
Validation deterministically rebuilds the expected manifest from the bound structured schema, fresh reconciliation, plan, context, and pending-publish checkpoint, then compares the complete decisions, services, aliases, phases, API paths, and bodies. If validation fails, print every reported mismatch and fail closed to the orchestrator. Do not execute or salvage individual operations and do not switch a supplied candidate to the standalone fallback.
Validate with --require-executable. Step 8 already performed the one fresh
bounded reconciliation for every approved exact table and all of its
columns/relationships/keys, including the child/parent/M:N relationship
capability managed properties. Missing capability evidence fails closed. If
the manifest remains non-executable, report its
verification conflicts to the orchestrator. Do not add another read loop,
change an approved decision, or enter fallback mode. A non-executable
candidate authorizes no metadata write.
If validation with --require-executable succeeds, set
<operation_manifest_mode> = valid and continue directly to Step 5's manifest
execution branch. This is the fast-v2 path: it skips the repeated
agent-driven full reconciliation, not any safety check.
Step 4 — Reconcile every planned table and column against the target
Telemetry checkpoint: reconcile_dataverse_schema
If <operation_manifest_mode> = valid, print:
✓ Approved operation manifest validated — complete fresh reconciliation and derived metadata coverage are bound to this environment.
Use its decisions as the reconciliation matrix and skip the remainder of
Step 4/4a. Continue to Step 5. A valid manifest has no unverified items; its
explicit reuse, adapt, and defer rows remain visible in the final
summary.
Print before starting:
"→ Reconciling every planned table and column against live target metadata before any write…"
Do not use the custom-table list as the source of truth, and do not issue one request per table. Fetch every plan entry (Reuse, Extend, or Create) — including standard and managed dependencies — in a single filtered query that also expands their columns:
On the scoped planning path, "every plan entry" means only the approved normalized contract and its required dependencies, never all saved-plan rows. Do not substitute the planning snapshot or inventory cache for this live read.
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
"EntityDefinitions?\$select=MetadataId,LogicalName,SchemaName,IsCustomEntity,IsManaged,IsCustomizable,CanCreateAttributes,PrimaryIdAttribute,PrimaryNameAttribute&\$filter=LogicalName eq '<table1>' or LogicalName eq '<table2>'&\$expand=Attributes(\$select=MetadataId,LogicalName,AttributeType,AttributeTypeName,RequiredLevel,IsManaged,IsCustomizable,IsPrimaryId,IsPrimaryName,SourceType,SourceTypeMask)" \
--tenant-id '<tenantId-from-resolve-environment>'
Build the $filter by OR-ing every planned logical name. This is the documented way to query multiple table definitions at once, and it replaces 2N requests (one entity GET plus one attributes GET per table) with one. Keep the $expand $select list to base AttributeMetadata properties only — a single query cannot cast to a derived column type, so fetch OptionSet details separately for the rare column that needs them.
Read the results as follows:
- A planned name present in
value[]— the table exists. Cache its expandedAttributesas that table's attribute snapshot for Steps 5a and 5b. - A planned name absent from
value[]— the table does not exist. This is the equivalent of a 404 in the matrix below. - Interpret
IsCustomizableandCanCreateAttributesas managed properties and read their.Valuefields.
If the batched query itself fails (non-2xx), retry it once; if it fails again, split it into per-table queries so one unreadable name cannot hide the rest. Any name still unreadable after that is unverified: STOP before writes for that reconciliation scope. Authentication, permission, timeout, and malformed-response failures are not evidence that a name is free. If the URL would exceed a practical length with very many tables, split it into a few filtered queries — still far fewer than one request per table.
Only if the plan contains alternate keys or M:N relationships, add the matching expands so Steps 5b and 5d never need their own per-item probes. EntityDefinitions also supports expanding Keys, ManyToManyRelationships, ManyToOneRelationships, and OneToManyRelationships:
&$expand=Attributes($select=...),Keys($select=SchemaName,KeyAttributes,EntityKeyIndexStatus),ManyToManyRelationships($select=SchemaName)
Do not add these expands when the plan has no keys or M:N relationships — they enlarge the response for no benefit, and standard tables carry many of both.
Step 4a — Targeted derived-metadata barrier
The base attribute snapshot is sufficient for ordinary columns, but it cannot prove that a same-named lookup, choice, Boolean, or computed column has the same semantics. Before classifying any such existing column as compatible:
Write the planned derived-column contract to
<working_dir>/.tmp/derived-metadata-expected.json. Each row contains:table,logicalName,kind,type,sourceType, plus:lookupTargetfor lookups;- exact integer/label
optionsfor Choice, MultiSelect Choice, and Boolean; - exact
sourceTypeMaskand serializedformulaDefinitionfor an explicitly approved, maker-created computed dependency.
Build one
BATCH-METADATAGET operation list for the affected existing tables only. Reuse one process/token and query:ManyToOneRelationshipsonce per child table containing planned lookups;- the applicable derived attribute collections
(
PicklistAttributeMetadata,MultiSelectPicklistAttributeMetadata,BooleanAttributeMetadata) once per table/type, expandingOptionSet; - the applicable typed attribute collection once per table/type for any
explicitly reused computed column, selecting
LogicalName,SourceType,SourceTypeMask,FormulaDefinition.
Do not issue one process per column and do not scan every customizable table. The exact planned names from Step 4 are the scope. Write the operation array to
<working_dir>/.tmp/derived-metadata-operations.json, then run:cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> \ BATCH-METADATA derived-reconciliation \ --operations "$(cat '<working_dir>/.tmp/derived-metadata-operations.json')" \ --tenant-id '<tenantId-from-resolve-environment>'Do not pass
--continue-on-error; the first unreadable required metadata collection must stop the barrier.Any non-2xx response, missing result slot, malformed option metadata, absent lookup target, or unavailable
FormulaDefinitionmakes that scopeunverified. STOP before writes. Authentication, throttling, permission, and parse failures are never compatibility evidence.Normalize the live results into
<working_dir>/.tmp/derived-metadata-live.json. Each row uses:table,logicalName,type,sourceType,sourceTypeMask,lookupTargets,options: [{ value, label }], andformulaDefinition. Lookup target arrays must contain exactly the approved target. Choice mappings must be non-empty with unique integer values and non-empty labels; Boolean mappings must contain exactly values 0 and 1. Then run:cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } node "${PLUGIN_ROOT}/scripts/validate-derived-metadata.js" \ --expected '<working_dir>/.tmp/derived-metadata-expected.json' \ --actual '<working_dir>/.tmp/derived-metadata-live.json'A lookup is compatible only when its complete target set matches. Planned choice values must exist with the same labels; extra live values are allowed. Ordinary planned columns require
SourceType0. A maker-created computed dependency is reusable only when its source type, source-type mask, and exactFormulaDefinitionmatch the approved artifact; theInvalidmask bit always blocks reuse.
This phase is read-only and uses the V2 long-lived executor. It must not add per-column child-process/token overhead back into the fast path.
Build and print a reconciliation matrix before Step 5:
| Target result | Table decision | Column decisions | Action |
|---|---|---|---|
| Present; all planned base and derived metadata compatible | reuse |
existing columns reuse |
No schema write. |
| Present; custom columns missing; table customizable and can create attributes | extend |
compatible reuse; absent custom create |
Queue missing ordinary columns for sequential creation; relationships remain Pass 2. |
| Absent; plan says Create; logical name uses the verified publisher prefix | create |
ordinary columns create inline; lookups deferred |
Create once after the complete-payload self-check. |
| Absent; plan says Reuse/Extend or dependency is standard/managed/required-existing | defer |
dependent columns defer |
Never recreate a standard or managed table. Drop the dependent lookups/columns from this run, continue with everything else, and list them under Deferred in Step 9. |
Present; same-name column has incompatible AttributeType / AttributeTypeName.Value |
extend |
incompatible column adapt |
Auto-rename the planned column via the probe sequence below, record it in the alias map, and create it alongside the existing one. Never modify or delete the existing column. |
Present; columns missing but IsCustomizable.Value=false or CanCreateAttributes.Value=false |
reuse |
missing columns defer |
The target cannot be extended by this workflow. Reuse the columns that do exist, drop the rest from this run, and list them under Deferred in Step 9. |
| Batched query failed (non-2xx) after retry and per-table split | unverified |
unknown | STOP before writes for the affected reconciliation scope and surface the concrete environment/auth/permission error. |
replace is not an automatic state in this workflow. Replacing a table or column requires an explicitly approved migration with dependency analysis and data movement, so a conflict resolves to adapt (rename beside it) or defer (leave it out) instead — both of which leave existing data untouched.
Decide-before-write barrier (HARD): finish reconciliation for every table and column before the first metadata write. Every item must come out of Step 4 as reuse, extend, create, adapt, or defer — never as an unresolved conflict. Deciding renames up front is what keeps relationships, screens, and sample data pointing at the same names.
No dead ends (HARD): a data-modelling conflict must never stop the run. Adapt it (rename beside the existing object) or defer it (drop it from this run), then keep going and report it in Step 9. Only environment faults stop this skill — failed auth, an environment mismatch, or a target the user has no privilege to write to. Those are not data-modelling problems and the user cannot resolve them by editing the plan.
Idempotency criterion (HARD): re-running this skill against an already-applied plan MUST perform zero metadata writes. Every table, column, relationship, key, and calc column resolves to reuse or an "already exists, skipped" outcome from the Step 4 snapshot. If a re-run issues any POST, the reconciliation missed something — report it rather than writing. Use this as the acceptance check after any change to Steps 4, 5, or 5a–5d.
Step 5 — Create / extend tables
Telemetry checkpoint: apply_dataverse_schema_changes
Valid operation-manifest execution branch
When <operation_manifest_mode> = valid, do not have an agent rebuild request
bodies. Read execution.phases in this fixed order:
tableCreates— dependency-tier table creates with all ordinary columns inline;extensions— missing ordinary columns on existing tables;relationships— lookups/1:N and M:N after both endpoints exist;alternateKeys— after target tables and columns exist;publish— onePublishXmloperation only when earlier phases contain writes or a bound publish-pending checkpoint requires retry.
For each non-empty phase, write just that phase's operations array to
<working_dir>/.tmp/dataverse-operation-phase-<name>.json. Read
integritySha256 and binding.reconciliationSha256 from the validated
manifest, then execute every phase with the same project-local atomic journal:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
EXECUTION_JOURNAL='<working_dir>/.tmp/dataverse-metadata-execution-journal.json'
ALL_MANIFEST_OPERATIONS='<working_dir>/.tmp/dataverse-operation-all.json'
# Write the flattened operations from every manifest phase to ALL_MANIFEST_OPERATIONS once.
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> \
BATCH-METADATA "manifest-<phase-name>" \
--operations "$(cat '<working_dir>/.tmp/dataverse-operation-phase-<name>.json')" \
--solution "<solution-uniquename>" \
--tenant-id "<tenantId>" \
--journal "$EXECUTION_JOURNAL" \
--manifest-file "$OPERATION_MANIFEST" \
--manifest-hash "<manifest.integritySha256>" \
--reconciliation-hash "<manifest.binding.reconciliationSha256>" \
--manifest-operations "$(cat "$ALL_MANIFEST_OPERATIONS")"
Wait for the entire phase to finish before starting the next. This executor is
not OData $batch; it sends one request at a time, reuses one token, preserves
manifest order, and stops on the first non-2xx response. Never pass
--continue-on-error, never parallelize phases or operations, and never
execute service.requiredTables through BATCH-METADATA.
The runner verifies the manifest file's integrity hash, requires the supplied
operation array to equal one complete manifest phase byte-for-byte, and rejects
that phase until every operation in preceding phases is journal-complete.
The runner atomically writes inFlight before each request and records each
successful operation before moving to the next. Completed fingerprints are
based on stable request identity, not the positional index; the complete
manifest's unique zero-based order is validated separately. Completed
fingerprints are skipped on an exact resume. If a process may have exited after Dataverse
accepted a request but before the journal completion write, the runner fails
with UNCERTAIN_METADATA_OPERATION; do not replay the old operation array.
Transport loss during a metadata mutation is immediately uncertain and is
never retried in-process; reads may retain transport retry behavior.
Perform a new bounded exact reconciliation, rebuild and revalidate the full
manifest, then resume with both new hashes. The runner mechanically treats an
uncertain operation omitted by the new manifest as already applied/superseded,
or retries it only when the fresh reconciliation proves it is still required.
If summary.metadataOperationCount is zero, issue zero metadata POSTs and
print ↻ Dataverse schema already fully applied — zero metadata writes. This
is the required idempotent rerun behavior after successful publish. A manifest
with zero schema operations but one checkpoint-driven PublishXml operation
must run that publish retry; it is not a zero-write completion.
The manifest builder writes
<working_dir>/.tmp/dataverse-publish-pending.json before any schema POST when
publish will be required. Leave this checkpoint in place after any schema or
publish failure. Delete it only after the validated publish phase returns
success. The next build validates its environment/solution/plan/contract
binding and integrity, merges its table list into the publish phase, and
therefore retries PublishXml even when every schema create is now
idempotently skipped.
On a hidden POST-time name collision, stop at the failed operation and discard
all not-yet-run phase arrays. The execution script must not choose Adapt or a
rename. Return to the existing planning revision path so the structured schema
artifact carries the approved Adapt names. Then perform a fresh bounded
reconciliation and regenerate the complete aliases, downstream relationship
and key bodies, service-required names, phases, manifest hashes, and phase
files. Revalidate before resuming through the journal. Never continue an old
array after a rename. Any non-collision failure stops the metadata path with
its exact result.
Before overwriting the old manifest, preserve its path. After the revised plan
and structured schema are approved through the existing flow, the top-level
planner/orchestrator must refresh the structured service dependencies and
mobile-plan-status.json receipt. This skill cannot create or restamp it.
Bind the contract through that pre-existing receipt, then roll the existing
publish checkpoint forward:
cd -- '<
…(truncated)