node-autotask 0.26.0 → 0.27.0

package/dist/operations/index.d.cts

@@ -1,7 +1,7 @@
-import { a as AutotaskClient, ec as BlindSurfaceInfo, ed as RelationshipResource, ee as BlindSurfaceInventory, ef as BlindSurfaceRow, eg as CreateBlockerKind, eh as CreateGuidanceReport, Z as ZoneName, ei as FieldCacheKind, i as AutotaskConfigError } from '../index-CKYr0unq.cjs';
-export { ej as FIELD_CACHE_KINDS } from '../index-CKYr0unq.cjs';
-import { I as Identifier, cK as EmptyReasonInfo, dM as PickListValue, a as FilterCondition } from '../index-1zBdJIEy.cjs';
-export { ht as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-1zBdJIEy.cjs';
+import { a as AutotaskClient, es as BlindSurfaceInfo, et as RelationshipResource, eu as BlindSurfaceInventory, ev as BlindSurfaceRow, ew as CreateGuidanceRow, ex as CreateBlockerKind, ey as CreateGuidanceReport, Z as ZoneName, ez as FieldCacheKind, j as AutotaskConfigError } from '../index-D4XYtn4s.cjs';
+export { eA as FIELD_CACHE_KINDS } from '../index-D4XYtn4s.cjs';
+import { I as Identifier, cO as EmptyReasonInfo, e4 as PickListValue, a as FilterCondition } from '../index-DQ9NgraW.cjs';
+export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-DQ9NgraW.cjs';
 import { CapabilityRecord } from '../capabilities.cjs';
 
 /**
@@ -423,6 +423,69 @@ interface ProbeReachabilityResult {
  */
 declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabilityOptions): Promise<ProbeReachabilityResult>;
 
+/**
+ * `effectiveRequiredFields` — the ONE precedence rule for "what does a create
+ * really require" (issue #219 N4).
+ *
+ * Three sources answer that question, at three different coverages, and the
+ * SDK used to leave the choice to each caller:
+ *   1. `createGuidance.liveProvenPrefix` — the fields a live create actually
+ *      demanded, in vendor-demand order (92 rows; the widest evidence);
+ *   2. `zoneFacts.createRequiredSet` — the hand-authored zone set (6
+ *      resources);
+ *   3. the vendor field catalog's `isRequired` — the spec opinion (wrong for
+ *      68 of the 75 resources that carry a proven prefix).
+ *
+ * The order is FIXED and stated: live-proven > zone > spec, with the source
+ * named on the result (`from`). Both plan shapes stay where they are; this
+ * helper is the only place in the SDK that compares them.
+ *
+ * Value-conditioned prefixes: a prefix proven for one picklist value (e.g.
+ * `contracts.create`'s type-1 `estimatedRevenue`/`estimatedHours`/
+ * `estimatedCost`) is still returned whole with `from: 'live-proven'` — the
+ * condition itself lives on the create-guidance row (`blocker.message` +
+ * `vendorEvidence`), which a caller must read before treating the list as
+ * unconditional. Never flatten a conditioned row into "all these fields are
+ * always required"; the row's evidence is the qualifier.
+ */
+
+/** Which source the returned field set came from (the precedence order). */
+type RequiredFieldsSource = 'live-proven' | 'zone' | 'spec';
+/** The effective required set + the source it came from. */
+interface EffectiveRequiredFields {
+    /** The required field names, in the source's own order (vendor-demand order for a live-proven prefix). */
+    fields: string[];
+    /** `live-proven` (createGuidance.liveProvenPrefix) > `zone` (createRequiredSet) > `spec` (vendor isRequired). */
+    from: RequiredFieldsSource;
+}
+/** The plan zone-fact shape this helper reads (both shapes stay plan-owned). */
+interface RequiredFieldsZoneFacts {
+    createRequiredSet?: string[];
+    createGuidance?: Pick<CreateGuidanceRow, 'liveProvenPrefix' | 'unproven'> | null;
+}
+/** The spec-side record this helper reads (the vendor field catalog's projection). */
+interface RequiredFieldsRecord {
+    /** The vendor `isRequired` field names (the narrowest source). */
+    requiredFields?: readonly string[] | null;
+}
+/**
+ * Resolve the effective create-required set for one resource.
+ *
+ * ```ts
+ * import { effectiveRequiredFields } from 'node-autotask/operations';
+ * const eff = effectiveRequiredFields(
+ *   { requiredFields: vendorRequiredNames },   // from operations.fieldCatalog
+ *   RELATIONSHIP_MAP.contacts.zoneFacts,       // the plan zone facts
+ * );
+ * // contacts: { fields: ['firstName', 'lastName', 'companyID', 'isActive'], from: 'live-proven' }
+ * ```
+ *
+ * An empty or absent higher source falls through to the next one; with no
+ * source at all the result is `{ fields: [], from: 'spec' }` — the name of the
+ * source is always stated, never a bare list.
+ */
+declare function effectiveRequiredFields(record?: RequiredFieldsRecord | null, zoneFacts?: RequiredFieldsZoneFacts | null): EffectiveRequiredFields;
+
 /** The closed blocker-kind set (the gate re-derives it; unknown kind → CONFIG_ERROR). */
 /**
  * The closed blocker-kind set served by `operations.createGuidance`.
@@ -432,6 +495,15 @@ declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabil
  * rather than forcing those rows into a misfitting class.
  */
 declare const CREATE_BLOCKER_KINDS: readonly CreateBlockerKind[];
+/** One served create-guidance row: the plan row plus the effective required set (issue #219 N4). */
+interface ServedCreateGuidanceRow extends CreateGuidanceRow {
+    /** The effective create-required set + the source it came from (`live-proven` > `zone` > `spec`). Read `blocker`/`vendorEvidence` before treating a value-conditioned prefix as unconditional. */
+    requiredFields: EffectiveRequiredFields;
+}
+/** The served report (the plan report with the effective required set on every row). */
+interface ServedCreateGuidanceReport extends Omit<CreateGuidanceReport, 'rows'> {
+    rows: ServedCreateGuidanceRow[];
+}
 /** The optional filter bag for `operations.createGuidance`. */
 interface CreateGuidanceOptions {
     /** The plan resource keys — narrows the row set. Unknown key → typed RESOURCE_UNKNOWN (zero wire). */
@@ -453,7 +525,7 @@ interface CreateGuidanceOptions {
  * @param client The wired client (unused — the served data is plan-pinned; the parameter exists so the op rides the invoke holder like every other operation).
  * @param opts   The optional filter bag ({ resources?, kind? }).
  */
-declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOptions): Promise<CreateGuidanceReport>;
+declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOptions): Promise<ServedCreateGuidanceReport>;
 
 /** entity (plan resource key) -> ExecuteCommand `Code` + id parameter name. */
 declare const ENTITIES: {
@@ -517,6 +589,34 @@ interface UiLinkResult {
 /** Zero-wire meta op: build the deep link from the client's live REST base (or an explicit `host`). */
 declare function uiLink(client: AutotaskClient, input: UiLinkInput): Promise<UiLinkResult>;
 
+/**
+ * Every entity name the registry resolves, mapped to its plan resource key.
+ * Derived from `apiEntity` (+ the singular entity-name alias) — never
+ * hand-written, so a plan resource lands here the moment it is generated.
+ */
+declare const ENTITY_TYPE_TO_RESOURCE: Readonly<Record<string, string>>;
+/**
+ * Resolve a vendor `referenceEntityType` to the plan resource key a caller
+ * would enumerate (the same derivation the field-catalog row serves as
+ * `targetResource`).
+ *
+ * ```ts
+ * import { resourceForEntityType } from 'node-autotask/operations';
+ * resourceForEntityType('CompanyLocation'); // 'company_locations'
+ * resourceForEntityType('Queue');           // null — the plan has no queue entity
+ * ```
+ *
+ * `null` means "the plan carries no resource for this vendor entity name" —
+ * it never guesses a near match. A blank/absent name resolves to `null`.
+ */
+declare function resourceForEntityType(entityType: string | null | undefined): string | null;
+/**
+ * True when `resource` is a plan resource with a read path (`query` or `get`) —
+ * the `targetEnumerable` half of the field-catalog row. A null/unknown key is
+ * false (a reference the plan cannot enumerate).
+ */
+declare function isEnumerableResource(resource: string | null | undefined): boolean;
+
 /** The pinned wire cap: `resources × include` above it is refused
  * pre-request (CONFIG_ERROR naming the computed cost and the cap) —
  * refused, never truncated. */
@@ -539,15 +639,38 @@ interface FieldCatalogFieldRow {
     type: string;
     isRequired: boolean;
     isReadOnly: boolean;
-    isQueryable: boolean;
+    /** The vendor `isQueryable` flag — ABSENT on a UDF row: the vendor reports UDFs as queryable, but a filter on a UDF name is accepted only with the `udf: true` marker, so the row states the mechanism in `filterable` instead of a boolean the vendor contradicts (issue #219 N7). */
+    isQueryable?: boolean;
     isPickList: boolean;
+    /** Present exactly on a UDF row: the filter mechanism a consumer must send to filter on this name (`udf: true` in the filter condition) — never infer plain filterability from the vendor's `isQueryable` (issue #219 N7). */
+    filterable?: 'udf-marker';
+    /** The write shape for an object/array field: `merge` (a sent subset is merged — `userDefinedFields` is the proven case) or `replace-all` (the vendor's full-model PUT replaces the collection). Absent on scalar fields (issue #219 N7). */
+    writeShape?: 'merge' | 'replace-all';
     /** The vendor `length` bound (null when the catalog names none). */
     maxLength: number | null;
     /** The referenced entity type for reference fields ('' when none). */
     referenceEntityType: string;
+    /** The plan resource key the referenced entity names (`resourceForEntityType`), or `null` when the plan carries no such resource — the key a caller enumerates valid ids with (issue #219 N1). Never a remedy or an enumeration hint. */
+    targetResource: string | null;
+    /** True exactly when `targetResource` is a plan resource with a `query`/`get` read path (issue #219 N1) — always served, so a reference the vendor names but the plan cannot enumerate reads `false`, never `undefined`. */
+    targetEnumerable: boolean;
+    /** Present exactly when the plan declares this field DERIVED for the resource (issue #219 N8): the vendor overwrites or inherits the value, so a submitted one is not authoritative. Distinct from `isReadOnly` (never write at all) — a derived field can be absent from that list and still be recomputed. */
+    derived?: DerivationRule;
     /** The vendor's exposed picklist VALUES, verbatim (present exactly when the `labels` opt is `true` and the vendor exposed values for this picklist field — the vendor-walled and non-picklist rows carry none). */
     picklistValues?: PickListValue[];
 }
+/** The derivation rule of one field (issue #219 N8) — a closed plan token, served without the field name it decorates. */
+interface DerivationRule {
+    /** elapsed(<start>,<end>) (recomputed from those timestamps) | parent (inherited from the parent record) | mirror(<field>) (the vendor copies that field) | external (written by another entity's op — writableRoute names it). */
+    rule: string;
+    /** The op that actually writes the value (the external rule names it — billing_item_approval_levels.create for a time entry's approval level). */
+    writableRoute?: string;
+}
+/** One declared derived field of a resource (issue #219 N8) — the declaration the plan pins. */
+interface FieldDerivation extends DerivationRule {
+    /** The vendor field name. */
+    field: string;
+}
 /** One per-resource fault (partial failures are typed PER ROW — never all-or-nothing). */
 interface FieldCatalogRowError {
     code: string;
@@ -561,8 +684,14 @@ interface FieldCatalogRow {
     apiEntity: string;
     /** True when the plan carries a `getUdfInfo` row for the resource (the vendor defines a UDF catalog endpoint for every entity resource — the catalog may answer an empty list). */
     udfCapable: boolean;
+    /** The filter mechanism for a UDF name — present exactly when `udfCapable`: a filter on a UDF name is accepted only with the vendor's `udf: true` marker (a plain filter is refused), so the row states the marker rather than leaving a consumer to read the UDF rows' `isQueryable` (issue #219 N7). */
+    udfFilter?: 'udf-marker';
+    /** The write shape of a record's `userDefinedFields` collection — present exactly when `udfCapable`: the vendor MERGES a sent list, so a subset is correct (issue #219 N7). */
+    udfWriteShape?: 'merge';
     /** The entity information model (present exactly when `info` was included and fetched). */
     info?: Record<string, unknown> | null;
+    /** The plan's derived-field declaration for this resource (issue #219 N8) — present exactly when the plan declares any, in plan order; the same list the create guidance row and the describe channel serve. Read it before treating a submitted field value as authoritative. */
+    derivedFields?: FieldDerivation[];
     /** The projected standard-field catalog (present exactly when `fields` was included and fetched; when the `fields` opt is given, only the matching rows — the requested names absent here land in `unmatchedFields`). */
     fields?: FieldCatalogFieldRow[];
     /** The requested `fields`-filter names absent from this resource's fields catalog (in request order); `[]` when no filter is given, when the row carries no fields catalog (an `info`/`udf`-only include or a row error), or when nothing was missing. Reported, never an error. */
@@ -938,4 +1067,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, EXPAND_RESOURCE_NAMES_MAX_IDS, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, ENTITY_TYPE_TO_RESOURCE, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };

package/dist/operations/index.d.ts

@@ -1,7 +1,7 @@
-import { a as AutotaskClient, ec as BlindSurfaceInfo, ed as RelationshipResource, ee as BlindSurfaceInventory, ef as BlindSurfaceRow, eg as CreateBlockerKind, eh as CreateGuidanceReport, Z as ZoneName, ei as FieldCacheKind, i as AutotaskConfigError } from '../index-C8QH3BkP.js';
-export { ej as FIELD_CACHE_KINDS } from '../index-C8QH3BkP.js';
-import { I as Identifier, cK as EmptyReasonInfo, dM as PickListValue, a as FilterCondition } from '../index-1zBdJIEy.js';
-export { ht as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-1zBdJIEy.js';
+import { a as AutotaskClient, es as BlindSurfaceInfo, et as RelationshipResource, eu as BlindSurfaceInventory, ev as BlindSurfaceRow, ew as CreateGuidanceRow, ex as CreateBlockerKind, ey as CreateGuidanceReport, Z as ZoneName, ez as FieldCacheKind, j as AutotaskConfigError } from '../index-BIWy9m-a.js';
+export { eA as FIELD_CACHE_KINDS } from '../index-BIWy9m-a.js';
+import { I as Identifier, cO as EmptyReasonInfo, e4 as PickListValue, a as FilterCondition } from '../index-DQ9NgraW.js';
+export { hV as PICKLIST_VALUE_NOT_SERVED_NOTE } from '../index-DQ9NgraW.js';
 import { CapabilityRecord } from '../capabilities.js';
 
 /**
@@ -423,6 +423,69 @@ interface ProbeReachabilityResult {
  */
 declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabilityOptions): Promise<ProbeReachabilityResult>;
 
+/**
+ * `effectiveRequiredFields` — the ONE precedence rule for "what does a create
+ * really require" (issue #219 N4).
+ *
+ * Three sources answer that question, at three different coverages, and the
+ * SDK used to leave the choice to each caller:
+ *   1. `createGuidance.liveProvenPrefix` — the fields a live create actually
+ *      demanded, in vendor-demand order (92 rows; the widest evidence);
+ *   2. `zoneFacts.createRequiredSet` — the hand-authored zone set (6
+ *      resources);
+ *   3. the vendor field catalog's `isRequired` — the spec opinion (wrong for
+ *      68 of the 75 resources that carry a proven prefix).
+ *
+ * The order is FIXED and stated: live-proven > zone > spec, with the source
+ * named on the result (`from`). Both plan shapes stay where they are; this
+ * helper is the only place in the SDK that compares them.
+ *
+ * Value-conditioned prefixes: a prefix proven for one picklist value (e.g.
+ * `contracts.create`'s type-1 `estimatedRevenue`/`estimatedHours`/
+ * `estimatedCost`) is still returned whole with `from: 'live-proven'` — the
+ * condition itself lives on the create-guidance row (`blocker.message` +
+ * `vendorEvidence`), which a caller must read before treating the list as
+ * unconditional. Never flatten a conditioned row into "all these fields are
+ * always required"; the row's evidence is the qualifier.
+ */
+
+/** Which source the returned field set came from (the precedence order). */
+type RequiredFieldsSource = 'live-proven' | 'zone' | 'spec';
+/** The effective required set + the source it came from. */
+interface EffectiveRequiredFields {
+    /** The required field names, in the source's own order (vendor-demand order for a live-proven prefix). */
+    fields: string[];
+    /** `live-proven` (createGuidance.liveProvenPrefix) > `zone` (createRequiredSet) > `spec` (vendor isRequired). */
+    from: RequiredFieldsSource;
+}
+/** The plan zone-fact shape this helper reads (both shapes stay plan-owned). */
+interface RequiredFieldsZoneFacts {
+    createRequiredSet?: string[];
+    createGuidance?: Pick<CreateGuidanceRow, 'liveProvenPrefix' | 'unproven'> | null;
+}
+/** The spec-side record this helper reads (the vendor field catalog's projection). */
+interface RequiredFieldsRecord {
+    /** The vendor `isRequired` field names (the narrowest source). */
+    requiredFields?: readonly string[] | null;
+}
+/**
+ * Resolve the effective create-required set for one resource.
+ *
+ * ```ts
+ * import { effectiveRequiredFields } from 'node-autotask/operations';
+ * const eff = effectiveRequiredFields(
+ *   { requiredFields: vendorRequiredNames },   // from operations.fieldCatalog
+ *   RELATIONSHIP_MAP.contacts.zoneFacts,       // the plan zone facts
+ * );
+ * // contacts: { fields: ['firstName', 'lastName', 'companyID', 'isActive'], from: 'live-proven' }
+ * ```
+ *
+ * An empty or absent higher source falls through to the next one; with no
+ * source at all the result is `{ fields: [], from: 'spec' }` — the name of the
+ * source is always stated, never a bare list.
+ */
+declare function effectiveRequiredFields(record?: RequiredFieldsRecord | null, zoneFacts?: RequiredFieldsZoneFacts | null): EffectiveRequiredFields;
+
 /** The closed blocker-kind set (the gate re-derives it; unknown kind → CONFIG_ERROR). */
 /**
  * The closed blocker-kind set served by `operations.createGuidance`.
@@ -432,6 +495,15 @@ declare function probeReachability(client: AutotaskClient, opts?: ProbeReachabil
  * rather than forcing those rows into a misfitting class.
  */
 declare const CREATE_BLOCKER_KINDS: readonly CreateBlockerKind[];
+/** One served create-guidance row: the plan row plus the effective required set (issue #219 N4). */
+interface ServedCreateGuidanceRow extends CreateGuidanceRow {
+    /** The effective create-required set + the source it came from (`live-proven` > `zone` > `spec`). Read `blocker`/`vendorEvidence` before treating a value-conditioned prefix as unconditional. */
+    requiredFields: EffectiveRequiredFields;
+}
+/** The served report (the plan report with the effective required set on every row). */
+interface ServedCreateGuidanceReport extends Omit<CreateGuidanceReport, 'rows'> {
+    rows: ServedCreateGuidanceRow[];
+}
 /** The optional filter bag for `operations.createGuidance`. */
 interface CreateGuidanceOptions {
     /** The plan resource keys — narrows the row set. Unknown key → typed RESOURCE_UNKNOWN (zero wire). */
@@ -453,7 +525,7 @@ interface CreateGuidanceOptions {
  * @param client The wired client (unused — the served data is plan-pinned; the parameter exists so the op rides the invoke holder like every other operation).
  * @param opts   The optional filter bag ({ resources?, kind? }).
  */
-declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOptions): Promise<CreateGuidanceReport>;
+declare function createGuidance(client: AutotaskClient, opts?: CreateGuidanceOptions): Promise<ServedCreateGuidanceReport>;
 
 /** entity (plan resource key) -> ExecuteCommand `Code` + id parameter name. */
 declare const ENTITIES: {
@@ -517,6 +589,34 @@ interface UiLinkResult {
 /** Zero-wire meta op: build the deep link from the client's live REST base (or an explicit `host`). */
 declare function uiLink(client: AutotaskClient, input: UiLinkInput): Promise<UiLinkResult>;
 
+/**
+ * Every entity name the registry resolves, mapped to its plan resource key.
+ * Derived from `apiEntity` (+ the singular entity-name alias) — never
+ * hand-written, so a plan resource lands here the moment it is generated.
+ */
+declare const ENTITY_TYPE_TO_RESOURCE: Readonly<Record<string, string>>;
+/**
+ * Resolve a vendor `referenceEntityType` to the plan resource key a caller
+ * would enumerate (the same derivation the field-catalog row serves as
+ * `targetResource`).
+ *
+ * ```ts
+ * import { resourceForEntityType } from 'node-autotask/operations';
+ * resourceForEntityType('CompanyLocation'); // 'company_locations'
+ * resourceForEntityType('Queue');           // null — the plan has no queue entity
+ * ```
+ *
+ * `null` means "the plan carries no resource for this vendor entity name" —
+ * it never guesses a near match. A blank/absent name resolves to `null`.
+ */
+declare function resourceForEntityType(entityType: string | null | undefined): string | null;
+/**
+ * True when `resource` is a plan resource with a read path (`query` or `get`) —
+ * the `targetEnumerable` half of the field-catalog row. A null/unknown key is
+ * false (a reference the plan cannot enumerate).
+ */
+declare function isEnumerableResource(resource: string | null | undefined): boolean;
+
 /** The pinned wire cap: `resources × include` above it is refused
  * pre-request (CONFIG_ERROR naming the computed cost and the cap) —
  * refused, never truncated. */
@@ -539,15 +639,38 @@ interface FieldCatalogFieldRow {
     type: string;
     isRequired: boolean;
     isReadOnly: boolean;
-    isQueryable: boolean;
+    /** The vendor `isQueryable` flag — ABSENT on a UDF row: the vendor reports UDFs as queryable, but a filter on a UDF name is accepted only with the `udf: true` marker, so the row states the mechanism in `filterable` instead of a boolean the vendor contradicts (issue #219 N7). */
+    isQueryable?: boolean;
     isPickList: boolean;
+    /** Present exactly on a UDF row: the filter mechanism a consumer must send to filter on this name (`udf: true` in the filter condition) — never infer plain filterability from the vendor's `isQueryable` (issue #219 N7). */
+    filterable?: 'udf-marker';
+    /** The write shape for an object/array field: `merge` (a sent subset is merged — `userDefinedFields` is the proven case) or `replace-all` (the vendor's full-model PUT replaces the collection). Absent on scalar fields (issue #219 N7). */
+    writeShape?: 'merge' | 'replace-all';
     /** The vendor `length` bound (null when the catalog names none). */
     maxLength: number | null;
     /** The referenced entity type for reference fields ('' when none). */
     referenceEntityType: string;
+    /** The plan resource key the referenced entity names (`resourceForEntityType`), or `null` when the plan carries no such resource — the key a caller enumerates valid ids with (issue #219 N1). Never a remedy or an enumeration hint. */
+    targetResource: string | null;
+    /** True exactly when `targetResource` is a plan resource with a `query`/`get` read path (issue #219 N1) — always served, so a reference the vendor names but the plan cannot enumerate reads `false`, never `undefined`. */
+    targetEnumerable: boolean;
+    /** Present exactly when the plan declares this field DERIVED for the resource (issue #219 N8): the vendor overwrites or inherits the value, so a submitted one is not authoritative. Distinct from `isReadOnly` (never write at all) — a derived field can be absent from that list and still be recomputed. */
+    derived?: DerivationRule;
     /** The vendor's exposed picklist VALUES, verbatim (present exactly when the `labels` opt is `true` and the vendor exposed values for this picklist field — the vendor-walled and non-picklist rows carry none). */
     picklistValues?: PickListValue[];
 }
+/** The derivation rule of one field (issue #219 N8) — a closed plan token, served without the field name it decorates. */
+interface DerivationRule {
+    /** elapsed(<start>,<end>) (recomputed from those timestamps) | parent (inherited from the parent record) | mirror(<field>) (the vendor copies that field) | external (written by another entity's op — writableRoute names it). */
+    rule: string;
+    /** The op that actually writes the value (the external rule names it — billing_item_approval_levels.create for a time entry's approval level). */
+    writableRoute?: string;
+}
+/** One declared derived field of a resource (issue #219 N8) — the declaration the plan pins. */
+interface FieldDerivation extends DerivationRule {
+    /** The vendor field name. */
+    field: string;
+}
 /** One per-resource fault (partial failures are typed PER ROW — never all-or-nothing). */
 interface FieldCatalogRowError {
     code: string;
@@ -561,8 +684,14 @@ interface FieldCatalogRow {
     apiEntity: string;
     /** True when the plan carries a `getUdfInfo` row for the resource (the vendor defines a UDF catalog endpoint for every entity resource — the catalog may answer an empty list). */
     udfCapable: boolean;
+    /** The filter mechanism for a UDF name — present exactly when `udfCapable`: a filter on a UDF name is accepted only with the vendor's `udf: true` marker (a plain filter is refused), so the row states the marker rather than leaving a consumer to read the UDF rows' `isQueryable` (issue #219 N7). */
+    udfFilter?: 'udf-marker';
+    /** The write shape of a record's `userDefinedFields` collection — present exactly when `udfCapable`: the vendor MERGES a sent list, so a subset is correct (issue #219 N7). */
+    udfWriteShape?: 'merge';
     /** The entity information model (present exactly when `info` was included and fetched). */
     info?: Record<string, unknown> | null;
+    /** The plan's derived-field declaration for this resource (issue #219 N8) — present exactly when the plan declares any, in plan order; the same list the create guidance row and the describe channel serve. Read it before treating a submitted field value as authoritative. */
+    derivedFields?: FieldDerivation[];
     /** The projected standard-field catalog (present exactly when `fields` was included and fetched; when the `fields` opt is given, only the matching rows — the requested names absent here land in `unmatchedFields`). */
     fields?: FieldCatalogFieldRow[];
     /** The requested `fields`-filter names absent from this resource's fields catalog (in request order); `[]` when no filter is given, when the row carries no fields catalog (an `info`/`udf`-only include or a row error), or when nothing was missing. Reported, never an error. */
@@ -938,4 +1067,4 @@ declare function invokeWrite(client: AutotaskClient, operation: string, args?: r
  */
 declare function invokeDelete(client: AutotaskClient, operation: string, args?: readonly unknown[] | Record<string, unknown>, opts?: InvokeOptions): Promise<unknown>;
 
-export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, EXPAND_RESOURCE_NAMES_MAX_IDS, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };
+export { AGGREGATE_DATE_BUCKETS, AGGREGATE_DEFAULT_LIMIT, AGGREGATE_DEFAULT_TOP, AGGREGATE_TOP_MAX, type AggregateGroup, type AggregateOptions, type AggregateResult, BLIND_SURFACE_KINDS, type BlindSurfaceKind, type BlindSurfaceOptions, BlindSurfaceRow, CREATE_BLOCKER_KINDS, type CreateGuidanceOptions, type DateBucket, type DerivationRule, ENTITY_TYPE_TO_RESOURCE, EXPAND_RESOURCE_NAMES_MAX_IDS, type EffectiveRequiredFields, type ExpandResourceNameRow, type ExpandResourceNamesOptions, type ExpandResourceNamesResult, FETCH_BY_IDS_CHUNK_SIZE, FETCH_BY_IDS_MAX_ITEMS, FETCH_MANY_MAX_ITEMS, FIELD_CATALOG_HONESTY_NOTE, type FetchByIdsOptions, type FetchManyItem, type FetchManyItemError, type FetchManyItemResult, type FetchManyOptions, type FetchManyResult, FieldCacheKind, type FieldCatalogFieldRow, type FieldCatalogOptions, type FieldCatalogResult, type FieldCatalogRow, type FieldCatalogRowError, type FieldDerivation, INVOKE_OPTION_KEYS, type InvokeMode, type InvokeOptions, MAX_FIELD_CATALOG_WIRE, PARAMS_BAG_KEYS, type ProbeReachabilityOptions, type ProbeReachabilityResult, type ProbeSurfaceRow, RECOVERY_CONFIRM, RECOVERY_DEFAULT_LIMIT, RECOVERY_MAX_LIMIT, type RecoveryDeleteBoundary, type RecoveryInput, type RecoveryMatch, type RecoveryOptions, type RecoveryResult, type RequiredFieldsRecord, type RequiredFieldsSource, type RequiredFieldsZoneFacts, type ResolveAnyOptions, type ResolveAnyResourceOutcome, type ResolveAnyResult, type SearchAcrossResourcesOptions, type SearchAcrossResourcesResult, type SearchAcrossResourcesRow, type ServedCreateGuidanceReport, type ServedCreateGuidanceRow, UI_LINK_ENTITIES, type UiLinkEntity, type UiLinkInput, type UiLinkResult, WORKFLOW_RESOURCES, aggregate, blindSurfaces, buildUiLink, createGuidance, dateBucketLabel, effectiveRequiredFields, expandResourceNames, fetchByIds, fetchMany, fieldCatalog, foldFlattenedOpts, invoke, invokeDelete, invokeRead, invokeWrite, isEnumerableResource, needsConfirmation, probeReachability, recovery, relationshipMap, resolveAny, resourceForEntityType, searchAcrossResources, uiLink, unknownKeysRefusal, validateDispatchArgs, validateFetchManyItems, validateInvokeOptions, validateParamsBag };

package/dist/operations/index.js

@@ -7,6 +7,7 @@ import {
   ConfirmationRequiredError,
   DELETE_BOUNDARY_NOTES,
   DeleteBoundaryError,
+  ENTITY_TYPE_TO_RESOURCE,
   EXPAND_RESOURCE_NAMES_MAX_IDS,
   FETCH_BY_IDS_CHUNK_SIZE,
   FETCH_BY_IDS_MAX_ITEMS,
@@ -35,15 +36,17 @@ import {
   fetchMany,
   fieldCatalog,
   isAutotaskError,
+  isEnumerableResource,
   isRecord,
   parseIdentifier,
+  resourceForEntityType,
   uiLink,
   validateFetchManyItems,
   validateQueryFieldNames
-} from "../chunk-SSUECUVN.js";
+} from "../chunk-42ZUISDH.js";
 import {
   CAPABILITIES
-} from "../chunk-QXWIQ67O.js";
+} from "../chunk-F7FVOXPQ.js";
 
 // src/operations/searchAcrossResources.ts
 var DEFAULT_LIMIT = 25;
@@ -609,6 +612,20 @@ async function probeReachability(client, opts) {
   return { results, wireUsed, cap, truncated: false };
 }
 
+// src/operations/requiredFields.ts
+function effectiveRequiredFields(record, zoneFacts) {
+  const prefix = zoneFacts?.createGuidance?.liveProvenPrefix;
+  if (Array.isArray(prefix) && prefix.length > 0) {
+    return { fields: [...prefix], from: "live-proven" };
+  }
+  const zoneSet = zoneFacts?.createRequiredSet;
+  if (Array.isArray(zoneSet) && zoneSet.length > 0) {
+    return { fields: [...zoneSet], from: "zone" };
+  }
+  const spec = record?.requiredFields;
+  return { fields: Array.isArray(spec) ? [...spec] : [], from: "spec" };
+}
+
 // src/operations/createGuidance.ts
 var CREATE_BLOCKER_KINDS = [
   "ok",
@@ -628,7 +645,13 @@ async function createGuidance(client, opts) {
       "createGuidance: opts must be an object { resources?: string[], kind?: CreateBlockerKind }"
     );
   }
-  let rows = CREATE_GUIDANCE.rows;
+  let servedRows = CREATE_GUIDANCE.rows.map((row) => ({
+    ...row,
+    // Issue #219 N4: one precedence rule, stated on every row (live-proven >
+    // zone > spec). The spec set is not available here (it is a LIVE read) —
+    // the helper is handed the plan's two shapes and names the source.
+    requiredFields: effectiveRequiredFields(void 0, RELATIONSHIP_MAP[row.resource]?.zoneFacts ?? null)
+  }));
   if (opts?.resources !== void 0) {
     if (!Array.isArray(opts.resources) || opts.resources.length === 0) {
       throw new AutotaskConfigError("createGuidance: opts.resources must be a non-empty string[] of plan resource keys");
@@ -651,7 +674,7 @@ async function createGuidance(client, opts) {
       }
       wanted.add(key);
     }
-    rows = rows.filter((row) => wanted.has(row.resource));
+    servedRows = servedRows.filter((row) => wanted.has(row.resource));
   }
   if (opts?.kind !== void 0) {
     if (!CREATE_BLOCKER_KINDS.includes(opts.kind)) {
@@ -659,13 +682,13 @@ async function createGuidance(client, opts) {
         `createGuidance: unknown kind "${String(opts.kind)}" \u2014 the valid kinds are: ${CREATE_BLOCKER_KINDS.join(", ")}`
       );
     }
-    rows = rows.filter((row) => row.blocker?.kind === opts.kind);
+    servedRows = servedRows.filter((row) => row.blocker?.kind === opts.kind);
   }
   return {
     zone: CREATE_GUIDANCE.zone,
     label: CREATE_GUIDANCE.label,
     verifiedAt: CREATE_GUIDANCE.verifiedAt,
-    rows,
+    rows: servedRows,
     counts: CREATE_GUIDANCE.counts
   };
 }
@@ -1384,6 +1407,7 @@ export {
   AGGREGATE_TOP_MAX,
   BLIND_SURFACE_KINDS,
   CREATE_BLOCKER_KINDS,
+  ENTITY_TYPE_TO_RESOURCE,
   EXPAND_RESOURCE_NAMES_MAX_IDS,
   FETCH_BY_IDS_CHUNK_SIZE,
   FETCH_BY_IDS_MAX_ITEMS,
@@ -1404,6 +1428,7 @@ export {
   buildUiLink,
   createGuidance,
   dateBucketLabel,
+  effectiveRequiredFields,
   expandResourceNames,
   fetchByIds,
   fetchMany,
@@ -1413,11 +1438,13 @@ export {
   invokeDelete,
   invokeRead,
   invokeWrite,
+  isEnumerableResource,
   needsConfirmation,
   probeReachability,
   recovery,
   relationshipMap,
   resolveAny,
+  resourceForEntityType,
   searchAcrossResources,
   uiLink,
   unknownKeysRefusal,

package/dist/pool.cjs

@@ -1,12 +1,13 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunk5OGJTS2Ecjs = require('./chunk-5OGJTS2E.cjs');
-require('./chunk-SG4LIVMG.cjs');
+var _chunkUHTZLUDEcjs = require('./chunk-UHTZLUDE.cjs');
+require('./chunk-5GGCSRT4.cjs');
 
 
 
-var _chunkHQGE4WAVcjs = require('./chunk-HQGE4WAV.cjs');
-require('./chunk-WM6E5O55.cjs');
+
+var _chunkZJ4ONAQFcjs = require('./chunk-ZJ4ONAQF.cjs');
+require('./chunk-5CC7LGNM.cjs');
 
 // src/pool.ts
 var _crypto = require('crypto');
@@ -31,20 +32,44 @@ function cacheSignature(config) {
 function createClientPool(options = {}) {
   const maxSize = _nullishCoalesce(options.maxSize, () => ( 128));
   if (!Number.isInteger(maxSize) || maxSize < 1) {
-    throw new (0, _chunkHQGE4WAVcjs.AutotaskConfigError)(
+    throw new (0, _chunkZJ4ONAQFcjs.AutotaskConfigError)(
       `ClientPool maxSize must be a positive integer (got ${String(options.maxSize)})`
     );
   }
   const idleTtlMs = options.idleTtlMs;
   if (idleTtlMs !== void 0 && (!Number.isInteger(idleTtlMs) || idleTtlMs < 1)) {
-    throw new (0, _chunkHQGE4WAVcjs.AutotaskConfigError)(
+    throw new (0, _chunkZJ4ONAQFcjs.AutotaskConfigError)(
       `ClientPool idleTtlMs must be a positive integer (got ${String(idleTtlMs)})`
     );
   }
-  const factory = _nullishCoalesce(options.factory, () => ( ((config) => new (0, _chunk5OGJTS2Ecjs.AutotaskClient)(config))));
+  const factory = _nullishCoalesce(options.factory, () => ( ((config) => new (0, _chunkUHTZLUDEcjs.AutotaskClient)(config))));
+  const sharedReadCache = options.sharedReadCache !== false;
   const entries = /* @__PURE__ */ new Map();
+  const readCaches = /* @__PURE__ */ new Map();
+  function sharedCacheFor(key, config) {
+    if (!sharedReadCache) return void 0;
+    const existing = readCaches.get(key);
+    if (existing !== void 0) {
+      readCaches.delete(key);
+      readCaches.set(key, existing);
+      return existing;
+    }
+    const created = _chunkZJ4ONAQFcjs.buildReadCache.call(void 0, config);
+    if (created === void 0) return void 0;
+    readCaches.set(key, created);
+    while (readCaches.size > maxSize) {
+      const oldest = readCaches.keys().next().value;
+      if (oldest === void 0) break;
+      readCaches.delete(oldest);
+    }
+    return created;
+  }
+  function withSharedCache(config, store) {
+    if (store === void 0 || config.cache === false) return config;
+    return { ...config, cache: { ..._nullishCoalesce(config.cache, () => ( {})), store } };
+  }
   function keyFor(config) {
-    const resolved = _chunkHQGE4WAVcjs.resolveCredentials.call(void 0, config);
+    const resolved = _chunkZJ4ONAQFcjs.resolveCredentials.call(void 0, config);
     const tuple = [
       resolved.userName,
       resolved.apiIntegrationCode,
@@ -80,7 +105,14 @@ function createClientPool(options = {}) {
         const oldest = entries.keys().next().value;
         if (oldest !== void 0) entries.delete(oldest);
       }
-      const created = { client: factory(config), usedAt: now, cacheSig: cacheSignature(config), warned: false };
+      const store = sharedCacheFor(key, config);
+      const created = {
+        client: factory(withSharedCache(config, store)),
+        usedAt: now,
+        cacheSig: cacheSignature(config),
+        // the CALLER's settings — the injected store is pool plumbing
+        warned: false
+      };
       entries.set(key, created);
       return created.client;
     },
@@ -89,6 +121,7 @@ function createClientPool(options = {}) {
     },
     clear() {
       entries.clear();
+      readCaches.clear();
     },
     get size() {
       return entries.size;