kalup 0.5.0 → 0.6.0

package/dist/commands.d.mts

@@ -1,4 +1,4 @@
-import { n as Prompter, r as Result, t as Handler } from "./context-0mrva_6H.mjs";
+import { n as Prompter, r as Result, t as Handler } from "./context-BgFzBPj9.mjs";
 import { Command } from "@oclif/core";
 //#region src/host/commands.d.ts
 /**

package/dist/commands.mjs

@@ -1,2 +1,2 @@
-import { _ as TargetRebindCommand, a as CompareCommand, c as InitCommand, d as PlanCommand, f as PullCommand, g as StatusCommand, h as StateRebuildCommand, i as COMMANDS, l as IrCommand, m as SnapshotCommand, n as ApplyCommand, o as DocsCommand, p as RmCommand, r as BlueprintUpgradeCommand, s as FmtCommand, t as AddCommand, u as KalupCommand, v as ValidateCommand } from "./commands-D_Q8-jc5.mjs";
+import { _ as TargetRebindCommand, a as CompareCommand, c as InitCommand, d as PlanCommand, f as PullCommand, g as StatusCommand, h as StateRebuildCommand, i as COMMANDS, l as IrCommand, m as SnapshotCommand, n as ApplyCommand, o as DocsCommand, p as RmCommand, r as BlueprintUpgradeCommand, s as FmtCommand, t as AddCommand, u as KalupCommand, v as ValidateCommand } from "./commands-DdogKJKg.mjs";
 export { AddCommand, ApplyCommand, BlueprintUpgradeCommand, COMMANDS, CompareCommand, DocsCommand, FmtCommand, InitCommand, IrCommand, KalupCommand, PlanCommand, PullCommand, RmCommand, SnapshotCommand, StateRebuildCommand, StatusCommand, TargetRebindCommand, ValidateCommand };

package/dist/{context-0mrva_6H.d.mts → context-BgFzBPj9.d.mts}

@@ -1271,6 +1271,16 @@ declare const issues: {
       output: string[];
     };
   };
+  W_SETTLING: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      output: string[];
+    };
+  };
   W_UNADDRESSABLE_NAME: {
     exit: string;
     title: string;

package/dist/{host-BkBYlh_7.mjs → host-BSYg3I66.mjs}

@@ -1,4 +1,4 @@
-import { A as sanitize, C as usageError, D as disclaimer, E as bin, O as escapeJson, S as versionText, T as KalupError, b as formats, k as exitCodes, u as KalupCommand, w as IssueError, x as version, y as PATH_MAX } from "./commands-D_Q8-jc5.mjs";
+import { A as sanitize, C as usageError, D as disclaimer, E as bin, O as escapeJson, S as versionText, T as KalupError, b as formats, k as exitCodes, u as KalupCommand, w as IssueError, x as version, y as PATH_MAX } from "./commands-DdogKJKg.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/host.d.mts

@@ -1,4 +1,4 @@
-import { i as ExitCode, n as Prompter, r as Result } from "./context-0mrva_6H.mjs";
+import { i as ExitCode, n as Prompter, r as Result } from "./context-BgFzBPj9.mjs";
 //#region src/host/host.d.ts
 interface Out {
   write: (text: string) => unknown;

package/dist/host.mjs

@@ -1,2 +1,2 @@
-import { n as isInteractive, r as run, t as execute } from "./host-BkBYlh_7.mjs";
+import { n as isInteractive, r as run, t as execute } from "./host-BSYg3I66.mjs";
 export { execute, isInteractive, run };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as isInteractive, r as run } from "./host-BkBYlh_7.mjs";
+import { n as isInteractive, r as run } from "./host-BSYg3I66.mjs";
 //#region src/index.ts
 process.exitCode = await run(process.argv.slice(2), {
 	cwd: process.cwd(),

package/dist/schemas/ir-1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kalup.dev/schemas/ir-1.schema.json",
   "title": "Kalup IR, version 1",
-  "description": "What a Kalup project's config files mean, derived by `kalup ir`, or what a portal holds, captured by `kalup snapshot` with an observation block. Change inside a version is additive and readers keep unknown fields, so the document and each resource accept fields this schema does not list. Below a resource everything is closed except `x` and the definition of a resource type this schema does not describe, which stays open until a later ir/1 release describes that type.",
+  "description": "What a Kalup project's config files mean, derived by `kalup ir`, or what a portal holds, captured by `kalup snapshot` with an observation block. Open for additions within ir/1 (docs/compatibility.md): the document, each resource and everything below it accept fields this schema does not list, and readers keep or ignore them; a later 1.x may add a resource type, and a reader reports an address of a type it does not handle as unknown. Closed, because a new value changes what a reader may conclude: generator, a $ref, a tombstone, the read statuses in coverage, lifecycle.options, and a target's drift and adopt.",
   "type": "object",
   "required": ["irVersion", "project", "generator", "resources", "targets", "tombstones"],
   "properties": {
@@ -277,23 +277,12 @@
           "$ref": "#/$defs/ref"
         },
         "type": {
-          "enum": ["string", "number", "bool", "date", "datetime", "enumeration", "phone_number"]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: string, number, bool, date, datetime, enumeration, phone_number. A later version may record one HubSpot adds."
         },
         "fieldType": {
-          "enum": [
-            "text",
-            "textarea",
-            "file",
-            "phonenumber",
-            "number",
-            "booleancheckbox",
-            "select",
-            "radio",
-            "checkbox",
-            "date",
-            "html",
-            "calculation_equation"
-          ]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: text, textarea, file, phonenumber, number, booleancheckbox, select, radio, checkbox, date, html, calculation_equation. A later version may record one HubSpot adds."
         },
         "description": {
           "type": "string"
@@ -318,7 +307,8 @@
           "minimum": -1
         },
         "numberDisplayHint": {
-          "enum": ["currency", "duration", "formatted", "percentage", "probability", "unformatted"]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: currency, duration, formatted, percentage, probability, unformatted. A later version may record one HubSpot adds."
         },
         "showCurrencySymbol": {
           "type": "boolean"
@@ -327,22 +317,15 @@
           "type": "string"
         },
         "textDisplayHint": {
-          "enum": [
-            "domain_name",
-            "email",
-            "ip_address",
-            "multi_line",
-            "phone_number",
-            "physical_address",
-            "postal_code",
-            "unformatted_single_line"
-          ]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: domain_name, email, ip_address, multi_line, phone_number, physical_address, postal_code, unformatted_single_line. A later version may record one HubSpot adds."
         },
         "calculationFormula": {
           "type": "string"
         },
         "dataSensitivity": {
-          "enum": ["non_sensitive", "sensitive", "highly_sensitive"]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: non_sensitive, sensitive, highly_sensitive. A later version may record one HubSpot adds."
         },
         "externalOptions": {
           "const": true
@@ -351,7 +334,7 @@
           "const": "OWNER"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "option": {
       "description": "One enumeration option. Array index is display order. The app alias lives in binding.aliases, never here.",
@@ -371,7 +354,10 @@
           "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true,
+      "patternProperties": {
+        "^as$": false
+      }
     },
     "groupDefinition": {
       "type": "object",
@@ -381,7 +367,7 @@
           "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "objectDefinition": {
       "description": "A custom object schema. Its properties and groups are resources of their own.",
@@ -399,7 +385,7 @@
               "type": "string"
             }
           },
-          "additionalProperties": false
+          "additionalProperties": true
         },
         "description": {
           "type": "string"
@@ -426,7 +412,7 @@
           }
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "pipelineDefinition": {
       "description": "A pipeline. Its stages are resources of their own; stages lists their IDs in display order.",
@@ -447,7 +433,7 @@
           }
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "stageDefinition": {
       "description": "A pipeline stage. Its metadata field depends on the object: probability on deals, ticketState on tickets, state on custom objects.",
@@ -463,13 +449,15 @@
           "maximum": 1
         },
         "ticketState": {
-          "enum": ["OPEN", "CLOSED"]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: OPEN, CLOSED. A later version may record one HubSpot adds."
         },
         "state": {
-          "enum": ["OPEN", "CLOSED"]
+          "type": "string",
+          "description": "A value HubSpot defines; known values: OPEN, CLOSED. A later version may record one HubSpot adds."
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "associationDefinition": {
       "description": "An association label between two objects: label as the from object shows it, inverseLabel as the to object does. With neither, the plain association of a pair that has no HubSpot-defined one.",
@@ -482,7 +470,7 @@
           "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "binding": {
       "description": "App terms, filled in by the loader. key and codec for properties, export for objects.",
@@ -492,19 +480,9 @@
           "type": "string"
         },
         "codec": {
-          "enum": [
-            "string",
-            "number",
-            "boolean",
-            "date",
-            "datetime",
-            "enum",
-            "multiEnum",
-            "stringArray",
-            "json",
-            "phoneNumber",
-            "owner"
-          ]
+          "type": "string",
+          "pattern": "^[a-zA-Z]+$",
+          "description": "The builder. Known: string, number, boolean, date, datetime, enum, multiEnum, stringArray, json, phoneNumber, owner. A later version may add a builder."
         },
         "aliases": {
           "type": "object",
@@ -525,7 +503,7 @@
           "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "lifecycle": {
       "type": "object",
@@ -550,7 +528,7 @@
           "type": "boolean"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "provenance": {
       "description": "Merged from blueprints.lock.json in the folder of object files by the loader. Absent means authored by hand.",
@@ -573,7 +551,7 @@
           "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "target": {
       "description": "One named portal. Credentials never enter the IR.",
@@ -614,7 +592,10 @@
           "additionalProperties": false
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true,
+      "patternProperties": {
+        "^credentials$": false
+      }
     },
     "override": {
       "type": "object",
@@ -635,7 +616,7 @@
           }
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "observation": {
       "description": "What a snapshot read: the target, when, and how completely. A portal-frontend document requires it. observedAt is the one timestamp an ir/1 document carries.",
@@ -665,7 +646,7 @@
           "$ref": "#/$defs/coverage"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "coverage": {
       "description": "What the read covered. Only a complete read proves that a resource is absent.",
@@ -695,52 +676,40 @@
             "const": "unknown"
           }
         },
-        "notCaptured": {
-          "description": "Documented response fields Kalup does not capture, per resource type.",
+        "settling": {
+          "description": "Resources the read cannot be trusted on yet, by address: apply wrote them minutes ago and HubSpot still serves an older copy (stale), or does not list one Kalup created (missing). Unknown until the time given, never absent or drifted.",
           "type": "object",
-          "required": ["property", "group", "object"],
-          "properties": {
-            "property": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            "group": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            "object": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            "pipeline": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            },
-            "stage": {
-              "type": "array",
-              "items": {
+          "additionalProperties": {
+            "type": "object",
+            "required": ["reason", "until"],
+            "properties": {
+              "reason": {
+                "type": "string",
+                "description": "Why it settles. Known: stale, missing. A later version may add a reason."
+              },
+              "until": {
                 "type": "string"
               }
             },
-            "association": {
+            "additionalProperties": true
+          }
+        },
+        "notCaptured": {
+          "description": "Documented response fields Kalup drops, by resource type. A later version may add a type.",
+          "type": "object",
+          "required": ["property", "group", "object"],
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[a-z]+$": {
               "type": "array",
               "items": {
                 "type": "string"
               }
             }
-          },
-          "additionalProperties": false
+          }
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "objectCoverage": {
       "type": "object",
@@ -830,7 +799,7 @@
               }
             }
           },
-          "additionalProperties": false
+          "additionalProperties": true
         },
         "excluded": {
           "description": "Addresses a skip override leaves out.",
@@ -861,7 +830,7 @@
               "type": "string"
             }
           },
-          "additionalProperties": false
+          "additionalProperties": true
         },
         "associations": {
           "description": "The associations of the pairs this object is in, pair by pair: per other object, whether the pair was read, and the user-defined types of this direction no name reached; and the HubSpot type IDs of each association addressed from this object. Absent when no pair with this object is in scope.",
@@ -884,10 +853,10 @@
               }
             }
           },
-          "additionalProperties": false
+          "additionalProperties": true
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "unsupportedProperty": {
       "description": "A present property Kalup does not write: no builder carries its type or fieldType, or HubSpot fills its options (owner or externalOptions). It is compared like any property but is not a resource.",
@@ -928,7 +897,7 @@
           "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "tombstone": {
       "description": "Written by `kalup rm`. destroy archives or deletes in the portal; release stops managing and leaves it.",
@@ -975,7 +944,7 @@
           }
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     }
   }
 }

package/dist/schemas/plan-1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kalup.dev/schemas/plan-1.schema.json",
   "title": "Kalup plan, version 1",
-  "description": "What `kalup plan` would do to one target, with the context an approval binds to. Closed at every level, so a saved plan carries nothing this schema does not name, and a new field is a new format version.",
+  "description": "What `kalup plan` would do to one target, with the context an approval binds to. Closed at every level, apart from the free-form values in a step's desired and expect.values, so a saved plan carries nothing this schema does not name. A later 1.x may add fields, values and step types; an earlier 1.x refuses a plan that uses one, before any request (docs/compatibility.md).",
   "type": "object",
   "required": [
     "format",
@@ -97,7 +97,9 @@
           "description": "The objects whose mode on this target is takeover, sorted.",
           "type": "array",
           "uniqueItems": true,
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         }
       },
       "additionalProperties": false
@@ -476,8 +478,12 @@
             "type": "object",
             "required": ["address", "desired"],
             "properties": {
-              "address": { "$ref": "#/$defs/address" },
-              "desired": { "type": "object" }
+              "address": {
+                "$ref": "#/$defs/address"
+              },
+              "desired": {
+                "type": "object"
+              }
             },
             "additionalProperties": false
           }
@@ -485,7 +491,9 @@
         "stageLabels": {
           "description": "Display only, never approved: the label of each stage a pipeline step's stage order names, config's else the portal's, so the plan text shows labels and not IDs.",
           "type": "object",
-          "additionalProperties": { "type": "string" }
+          "additionalProperties": {
+            "type": "string"
+          }
         },
         "ignoreChanges": {
           "description": "Create only: set on create, released after.",
@@ -783,7 +791,8 @@
             "override",
             "unsupported",
             "not-owned",
-            "policy"
+            "policy",
+            "settling"
           ]
         },
         "detail": {

package/dist/schemas/state-1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kalup.dev/schemas/state-1.schema.json",
   "title": "Kalup portal state, version 1",
-  "description": ".kalup/state/portal-<portalId>.json. Describes one verified portal, not the code, and holds no target name. Covered by the compatibility policy (docs/compatibility.md): closed at every level apart from the free-form values in an entry's base and rewrites, so a new field is a new format version. No tokens, record data, unowned fields or unmanaged resources.",
+  "description": ".kalup/state/portal-<portalId>.json. Describes one verified portal, not the code, and holds no target name. Covered by the compatibility policy (docs/compatibility.md). Open for additions within kalup.state/1: a later 1.x may add top-level fields, resource entries of types this version does not plan, and fields on an entry. A reader keeps what it does not know: it never drops an entry of a type it does not handle or a top-level field it does not know, and it drops an entry's unknown fields only when it rewrites that entry. lastApply, an entry's attested and rewrites, and the base's option members stay closed. Kalup never writes a key, record data, unowned fields or unmanaged resources: its state writer refuses a file holding anything shaped like a key.",
   "type": "object",
   "required": ["format", "lineage", "serial", "portalId", "resources"],
   "properties": {
@@ -58,15 +58,16 @@
       "additionalProperties": false
     }
   },
-  "additionalProperties": false,
+  "additionalProperties": true,
   "$defs": {
     "resourceState": {
       "type": "object",
       "required": ["origin", "id"],
       "properties": {
         "origin": {
-          "description": "created and adopted are owned. pulled owns nothing: pull recorded the base of a resource no entry owned, and a plan still adopts it.",
-          "enum": ["created", "adopted", "reference", "pulled"]
+          "description": "created and adopted are owned. pulled owns nothing: pull recorded the base of a resource no entry owned, and a plan still adopts it. reference owns nothing. Another value, from a later 1.x, owns nothing here.",
+          "type": "string",
+          "pattern": "^[a-z]+$"
         },
         "id": {
           "description": "The portal name the entry owns. It owns the resource only while this equals the name the address resolves to. null for runbook-only types.",
@@ -119,9 +120,20 @@
           "items": {
             "type": "integer"
           }
+        },
+        "written": {
+          "description": "The units apply wrote within the settling window before its last write, each with when it verified the write. For a few minutes HubSpot may serve an older copy, so a read that disagrees on such a unit is settling: unknown, never drift.",
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "writtenAt": {
+          "description": "When apply last verified a write to the resource, whatever units it named. A read that does not show the resource within the settling window after it is settling: unknown, never absence.",
+          "type": "string"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "base": {
       "description": "Per owned unit, the value config and portal last agreed on; possibly partial. Scalar units by field name. options: a map keyed by option value whose members hold the agreed label, hidden and description; a member with no fields means only its membership is agreed. optionsOrder: the agreed order of the members both sides held.",

package/docs/compare.md

@@ -30,7 +30,7 @@ Every address present on either side, including properties Kalup does not write,
 - `differs`: `changes[]` lists options to add or remove; `held[]` lists units that differ, `diverged` since there is no base; `notes[]` lists options only `b` holds, kept because options are additive. When `b` is a portal side, the note names the pull command that brings the option into config. `pull` does not write a resource that names a portal name a `name` override shadows (`shadowed:<name>`), so on such a resource the note says to correct or remove that override instead. Nor does it bring in a property the files lack that is outside its object's pull scope, so there the note says to add the name to `objects.<object>.include`; a property the files define is always in scope. A snapshot does not record whether HubSpot defines a property, so on a reference `include` does not name, a snapshot's note says it may be outside the scope and gives the same advice.
 - `only-a` or `only-b`: on one side only.
 - `unmanaged`: only a portal side holds it and the other side is config. Listed and counted, never a difference: absence never deletes.
-- `unknown`: a side could not read its object, never read it, left out a property config names because its group's name holds whitespace (`W_UNADDRESSABLE_NAME`), or a target side has a `lookup` override, since this version manages no lookup resources. `reason` says which side and why.
+- `unknown`: a side could not read its object, never read it, left out a property config names because its group's name holds whitespace (`W_UNADDRESSABLE_NAME`), is settling after an apply (plan.md, `W_SETTLING`; the fix says when to compare again, or for a snapshot side when to take a new one), may be a type HubSpot's schema read does not name yet, or a target side has a `lookup` override, since this version manages no lookup resources. A snapshot a later version of Kalup took may hold a type this version does not handle: against config its addresses are `unmanaged`, since config never names them; against a target or another snapshot they are `unknown`, and the fix says to compare with a later version. When such a snapshot's read was incomplete and its coverage records parts this version does not know, what it lacks is `unknown` too, never absent. `reason` says which side and why.
 - `excluded`: a `skip` override, or outside a side's read scope. Listed, not a difference.
 
 Config owns the fields it states, less `ignoreChanges`; a reference owns nothing, so only its presence compares. A portal side owns every field it captured; a field HubSpot left out takes its default, or `null` when it has none. With config as `b`, only the fields config states are compared. Options are compared when the config side states them, and always between two portal sides. Config managing what the portal holds as HubSpot-defined or calculated differs in the unit `managed`.

package/docs/errors/E_PLAN_INVALID.md

@@ -6,6 +6,8 @@
 
 The file named on the command line is missing, is not JSON, or does not match the `plan/1` schema. The message names the first place that fails. Apply also refuses a file whose steps contradict themselves: a change that writes a value the step's `desired` values do not hold, or a custom object archive whose `expect` does not count the properties, groups and pipelines it takes along. `kalup plan` never writes such a file.
 
+A step of a resource type this version does not handle: a later version of Kalup made the plan. The message names the step and that version. Apply the plan with it, or a later one.
+
 ## Fix
 
 Save the plan again with `kalup plan --target <name> --out <file>`, review it, and apply that file. Never edit a plan file by hand.

package/docs/errors/W_SETTLING.md

@@ -0,0 +1,19 @@
+# W_SETTLING
+
+A warning from every command that reads a target: for some minutes after a write HubSpot may serve an older copy of what was written, so the read cannot be trusted on those resources yet. Exit stays 0, except as below.
+
+## When
+
+After `apply` verifies a write, state records when it did and the units it wrote. For 5 minutes after that, a read that shows another value than apply verified on one of those units, or does not show the resource, is settling: HubSpot has been seen to serve a custom object schema's fields from before a PATCH, to leave a new custom object out of the schemas list, and to leave a new association's name out of its schema read for about 5 minutes. A label HubSpot lists that its schema read does not name yet settles the same way.
+
+A settling resource is unknown, never absent, drifted or held: `plan` blocks its step with reason `settling` and never creates, deletes or writes it, a destroy tombstone on it included, `pull` keeps the file as it is, `compare` reports it `unknown` (`E_INCOMPLETE`, exit 1), and the read is incomplete. Takeover waits only while something on the object it removes from settles; `state rebuild --write` and `target rebind` only while something config names does. Its base in state never moves on such a read. A difference on a unit apply did not write is drift as ever.
+
+## Fix
+
+Run the command again after the time the warning names. Nothing to change.
+
+## Example
+
+```
+W_SETTLING: HubSpot still serves an older copy of 1 resource apply wrote minutes ago, so this read is not trusted on it until 2026-10-06T09:05:00.000Z: property:companies/billing_status (fix: run the command again after 2026-10-06T09:05:00.000Z) (docs: errors/W_SETTLING.md)
+```

package/docs/plan.md

@@ -39,12 +39,14 @@ With `drift: 'overwrite'`, drift and conflicts are written labelled `reverts-ui-
 
 ## What blocks
 
-The first rule that matches: a `skip` override (no step, `coverage.excluded`); a `lookup` override; an unread object (`scope`, action `unknown`); a blocked parent or missing group (`dependency-blocked`); a property Kalup does not write (pull.md), whose fix makes it a `p.string` reference; for a create, a missing `name` override target, an archived property name (a create restores it; an archived group's name is created anew), or no limit room; HubSpot-defined or calculated, a `type` or `hasUniqueValue` difference, or read-only definition or options.
+The first rule that matches: a `skip` override (no step, `coverage.excluded`); a `lookup` override; a resource settling after an apply (`settling`, action `unknown`, below); an unread object (`scope`, action `unknown`); a blocked parent or missing group (`dependency-blocked`); a property Kalup does not write (pull.md), whose fix makes it a `p.string` reference; for a create, a missing `name` override target, an archived property name (a create restores it; an archived group's name is created anew), or no limit room; HubSpot-defined or calculated, a `type` or `hasUniqueValue` difference, or read-only definition or options.
+
+For 5 minutes after apply wrote a unit and read it back, HubSpot can still serve the copy from before the write. So within that window a read that shows another value than the base on a unit apply wrote, or leaves out a resource apply wrote, makes the resource settling, with what lies under a custom object left out that way (what is under a resource HubSpot serves an older copy of plans as ever): its step is `unknown`, blocked `settling`, its fix says when to plan again, and `W_SETTLING` warns. Nothing is held, created, deleted or written for it, a destroy tombstone's release or delete included, and the read is incomplete. A release tombstone still releases. A difference on a unit apply did not write is drift as ever, and after the window the read is believed again. State records what apply wrote and when in each entry's `written` and `writtenAt`. Takeover waits only while a property or group of the object it removes from settles.
 
 ## Custom objects
 
 - A new custom object is one `create` step. Apply creates it with its name, labels and description, then its groups and properties, then sets the display, required and searchable properties, since HubSpot refuses those fields until the properties they name exist. The step's notes say what HubSpot adds to a new object (its own properties, the group `<name>_information` and associations with activities) and which fields wait for the properties. When the object file lists `<name>_information`, as a pull writes it once a property sits in it, that group's create step notes that apply gives HubSpot's group config's label instead.
-- HubSpot's schemas list can show a custom object's values from before a write for some seconds after apply verified it, so a plan made right after such an apply can show the write as held drift. Plan again a minute later, and do not pull in that window: the pull would take the old values into config.
+- HubSpot's schemas list can show a custom object's values from before a write for some seconds after apply verified it, and can leave out an object just created. A plan made then blocks the object `settling` (above), never holds the write as drift.
 - An update writes the whole schema in one request. A create and every update are `safe`: the display fields change forms and record views, not record values. A delete is `destructive`.
 - Blocked `unsupported`: a create whose name HubSpot holds archived, since the create would purge the archived object with its records and association labels (restore it in HubSpot and pull, purge it in HubSpot, or choose another name); a create whose name differs only in case from a custom object HubSpot holds, since HubSpot keeps names unique ignoring case; and a create or update whose display, required or searchable field names a property the portal does not hold and the plan does not create. When the plan blocks that property's create (a limit, for example), the object's step is blocked `dependency-blocked`, naming the property.
 - `kalup rm object:<name>` writes one tombstone that covers everything on the object: the plan has one delete step, which archives the object. Its title says how many of the object's properties, groups and pipelines go with it, and that HubSpot keeps no properties on an archived custom object; apply stops before any write when its own read finds more than the plan did. When the key cannot read the object's pipelines, the step is blocked `scope`, since the plan cannot count them. HubSpot refuses the archive while the object holds records. A tombstone on something under the object that asks otherwise than the object's is blocked with the reason. Takeover never archives a custom object.
@@ -69,7 +71,7 @@ The first rule that matches: a `skip` override (no step, `coverage.excluded`); a
 - An update sends both labels. Risk: a create and an update are `safe`; a delete is `destructive`, since records lose the association.
 - A plain association delete is blocked `unsupported` while a label of its pair remains, one HubSpot does not name yet included, unless the plan deletes that label first: HubSpot refuses it.
 - Blocked `unsupported` too: a plain association config gives a label, or a label config holds as a plain association (add an entry under another name instead); a create whose label the pair shows already from the same object, a plain create on a pair that holds a plain association, and a label create that fits HubSpot's cap only once a delete in this plan has run (deletes run last: apply the delete, then plan again).
-- An association the read did not find, on a pair whose lists hold a type HubSpot's schema read does not name yet, is blocked: it may be that type. Plan again in a few minutes.
+- An association the read did not find, on a pair whose lists hold a type HubSpot's schema read does not name yet, is blocked `settling`: it may be that type. `W_SETTLING` warns, and the read is incomplete. Plan again in a few minutes.
 - HubSpot holds at most 50 labels per pair. Plan warns `W_LIMIT_HEADROOM` when its creates would pass the count Limits Tracking reports, and never blocks on it; HubSpot refuses the 51st with HTTP 437, which apply reports.
 - Blocked `scope`: an association of a pair whose labels were not read or answered 403.
 - Takeover never deletes an association. `notCovered` names association limits, which Kalup does not manage yet.

package/docs/pull.md

@@ -64,6 +64,8 @@ Where state holds agreed values for a resource (its base), each unit is compared
 
 `--accept <address[#unit]>` (repeatable, `*` as in `--only`) takes the portal side of those units, as each kept line prints; one matching nothing is `E_ACCEPT_UNMATCHED`.
 
+A resource settling after an apply (plan.md) is left as the file has it and gets no base, as for an address `--only` leaves out, with `W_SETTLING`: for minutes after a write HubSpot can serve the copy from before it, and pulling that copy would undo the change in config. `--check --exit-code` counts it as pending, exit 2.
+
 After the files are written, and only after a complete read, pull records in state the base of every unit the files and the portal agree on, for the addresses `--only` selects: under the portal lock (`E_LOCKED`) with the serial check, as apply saves. An owned entry keeps its origin; an address no entry owns gets origin `pulled`, which owns nothing: the next plan still adopts it, but compares against that base, so a later file edit is a `config-change`, not `diverged`. A field the files leave out because HubSpot holds its default (an empty description, `formField` off, an option with no description) is recorded at that default, so adding it to the file later is a `config-change` too. A unit that still differs keeps its base. `--check` and `--discover` record nothing and take no lock. A plan saved before the pull no longer applies (`E_STATE_CHANGED`). The pull that creates the state file prints its path. A new object file that gets more than 200 properties warns `W_LARGE_SCOPE`: the scope `init` writes takes every custom property.
 
 ## Target overrides

package/docs/snapshot.md

@@ -31,7 +31,7 @@ A snapshot holds the scope and the captured fields, and is no backup of the port
 
 ## Incomplete reads
 
-The file is still written, with `complete: false`, the objects not read marked `unreadable` and `unaddressable` properties listed, and `W_INCOMPLETE` names the fix. The exit stays 0.
+The file is still written, with `complete: false`, the objects not read marked `unreadable` and `unaddressable` properties listed, and `W_INCOMPLETE` names the fix. The exit stays 0. A resource settling after an apply (plan.md) is listed under `coverage.settling` with when its window ends, compare reports it unknown, and `W_INCOMPLETE` says to take a new snapshot after that time.
 
 ## Output