@spottoai/types-package 1.0.2-beta.99 → 1.0.2-dev1138.12

package/README.md

@@ -37,11 +37,149 @@ Or for a specific branch/tag:
 
 ```typescript
 // Import all interfaces
-import * as Types from '@spotto/types-package';
+import * as Types from '@spottoai/types-package';
 
 // Import specific interfaces
-import { User } from '@spotto/types-package';
+import { User } from '@spottoai/types-package';
+
+// Import AWS-only public artifact contracts
+import type { AwsPortalAccountSummaryArtifact, AwsPortalResourceCollectionArtifact } from '@spottoai/types-package/aws';
+
+// Import AWS relationship or commitments validators without loading the
+// compatibility-wide AWS barrel.
+import { validateAwsPortalRelationshipArtifact } from '@spottoai/types-package/aws/relationships';
+import { validateAwsCommitmentsPlanningViewIdentity } from '@spottoai/types-package/aws/commitments-planning';
+
+// Import the current financial authority contract family without the wider root barrel.
+import { isFinancialScopeBaselineEnvelopeV2 } from '@spottoai/types-package/azure/financial-scope';
 ```
+
+The retired `azure/financial-baseline` V1 probe is not a compatibility entry point. Current evidence, owner/aggregate baseline, projection, authority-view, and savings-authority contracts are exported by `azure/financial-scope` and the package root.
+
+The root entry point also exports the provider-neutral artifact generation,
+manifest, descriptor, and completed-pointer contracts. Storage paths and
+runtime persistence records deliberately remain owned by the producing engine.
+
+The root entry point exports the provider-neutral artifact-evidence vocabulary,
+revision comparison, immutable billing analyzer V2 documents, and enforced
+Azure view-generation contracts. An absent `ownershipEpochRevision` is valid
+only for observe-mode evidence: an observe request or an unpromoted manifest
+without an epoch must never become authority. Enforce-mode requests and every
+promoted billing or coordinated-view pointer require a positive, matching epoch
+in both ownership and revision data. `npm run check:artifact-evidence-contracts`
+executes the canonical cross-runtime corpus, billing validator matrix, ownership
+checks, promotion preconditions, and every revision-comparison outcome.
+
+Claim-projected Azure views use `PublishedViewManifestV4` for one Portal or
+Plugin surface and `PublishedAzureViewSetV3` for the coordinated promoted pair.
+A surface may have `complete` or `partial` coverage, but every projected
+artifact must bind its exact section selectors only to completed claims. The
+coordinated pointer remains enforceable-only and therefore requires a positive,
+matching ownership epoch. Existing `CompletedViewManifestV3` and
+`CompletedAzureViewSetV2` retain their fully-completed semantics for N-1
+readers. Producers and readers share the bounded collection limits exported as
+`PUBLISHED_VIEW_OBJECT_LIMITS_V1`.
+
+Observe-mode discovery uses `BillingAnalyzerInputObservationPointerV1` and
+`BillingAnalysisPromotionObservationV1`. Both are explicitly
+`diagnostic-only`, may never substitute for a current authority pointer, and
+may omit an ownership epoch only when ownership and revision omit it together.
+The promotion observation has a stable exact-field canonicalizer that excludes
+its own `observationDigest` and ignores additive-next fields. An epoch-free
+promotion observation must report `unenforceable` / `not-enforceable`; a
+matching present epoch must not report that pair. Current-pointer validators
+explicitly reject these diagnostic discriminants while retaining unrelated
+additive-next fields.
+
+Portable billing contract corpus v7 pins the shared stored/decoded object
+limits, safe `latest-enqueued.json` diagnostic discovery path, strict V1/V2/
+legacy-fallback response authority, prototype-key rejection, bounded iterative
+control-data traversal, and exact metadata/plot descriptor boundaries. The
+corpus contains 351 cases and 436 mutations at SHA-256
+`508cb1bfb27ec89e1b99fbada05e91bffe8d4c84174492760b647fd7311d5f5a`;
+its three promotion-observation digest vectors remain byte-for-byte compatible
+with v5.
+
+For an epoch-bound promotion observation, `evaluation.outputDigestRelation` is
+an optional V1 compatibility extension. Equal revisions may omit it only for
+the legacy `would-be-idempotent` shape; `same` also requires
+`would-be-idempotent`, while `different` requires `would-quarantine`. Every
+non-equal comparison forbids the relation. When present, the relation is part
+of the canonical observation preimage and therefore bound by
+`observationDigest`; legacy observations retain their original preimage.
+
+Billing output V2 uses an acyclic digest chain. Producers project the public
+`BillingOutputBindingV1`, canonicalize it with
+`canonicalizeBillingOutputBindingV1`, and SHA-256 that UTF-8 preimage to obtain
+`outputBindingDigest` (B). Exact stored metadata bytes containing B are hashed
+into the metadata descriptor; the canonical output manifest containing B and
+all descriptors is then hashed, excluding only its own top-level
+`manifestDigest`, to obtain D. `BillingAnalysisCurrentPointerV1` keeps D in
+`outputManifestDigest`. The package also exports canonical preimage helpers for
+both billing manifest versions; hashing remains a platform-boundary concern and
+the package has no Node crypto dependency.
+
+Canonical gzip artifacts require a fixed writer implementation/version,
+`mtime=0`, and fixed header/options. Descriptors hash the exact compressed bytes,
+not decompressed JSON. Readers must reject duplicate JSON keys before applying
+the structural validators or canonical digest checks.
+
+The root entry point exports one provider-aware `CommitmentsPlanningView` for
+Azure and AWS. Existing Azure artifacts remain compatible through the legacy
+branch, while the AWS branch requires a minimal account identity, `aws-native`
+source evidence, linked-account scope metadata, and provider-specific inventory
+shapes without introducing an AWS-only planning DTO.
+
+The root and `/aws` entry points also own the immutable AWS Commitments Planning
+Portal envelope, `commitments-planning.json.gz` logical name, artifact registry
+relationship, and dependency-free allowlist validator. The validator binds the
+envelope, provider scope, nested applied scopes, and account-bearing ARNs while
+rejecting internal metadata, Azure-only fields, and undeclared public fields.
+
+The same entry points expose a separate organization commitments contract
+family: a secret-free `organization-commitments` refresh command, a safe scope
+selector and progress response, a payer-aware planning view, and the immutable
+`organization-commitments-planning.json.gz` artifact. Its validator binds the
+company, estate, manifest revision, organization, management account, exact
+member set, and account-bearing ARNs without weakening the exact-account
+validator. Allocation and resource attribution remain explicitly unavailable
+until a producer supplies proved persisted evidence.
+
+The stable `/aws/relationships` and `/aws/commitments-planning` entry points
+expose those runtime contracts independently for browser consumers. The root
+and `/aws` barrels remain compatibility entry points and continue to export the
+same symbols. Package `import` conditions use tree-shakable native ESM while
+`require` conditions retain the CommonJS compatibility build.
+
+The root and `/aws` entry points export the secret-free `AwsEstatesManifest`,
+AWS estate/account/billing-source command union, and company trust-setup
+contracts. The API-owned desired-state document is stored as
+`companies/{companyId}/aws/aws-estates.json`; commands reference its opaque
+revision instead of copying role, billing-export, External ID, or credential
+configuration. Engine saga and persistence records remain engine-owned.
+
+The root and `/aws` entry points also export the lossless AWS plugin
+subscription/resource body contracts, deterministic logical-name builders, one
+complete active-set manifest, and dependency-free runtime validators. These
+validators are the bounded shared rejection boundary required for immutable
+plugin publication; they perform no I/O.
+
+The same entry points export the lossless AWS resource collection, account
+summary, compact retained-history, retained body-reference, and audience-indexed
+AI cost-summary contracts. Package-owned logical names and dependency-free
+validators bind exact account/scope/generation/sibling identity while rejecting
+undeclared, credential-bearing, physical-path, operational-marker, and lossy
+bodies.
+
+They also export the lossless relationship-schema-v2 AWS graph contract and
+validator. The graph is scoped by AWS account and Region, supports account,
+Region, resource, and synthetic nodes without Azure resource groups, and
+retains closed topology, aggregate family freshness, cost provenance,
+unresolved references, and honest truncation evidence.
+`PublicRelationshipArtifact` is the provider-aware Azure-or-AWS consumer union;
+the former reduced AWS declaration remains available under the explicit
+`AwsPortalRelationshipArtifactV1` migration name.
+
 ## Development
 
 ### Setup
@@ -92,11 +230,14 @@ src/
 
 ## Versioning
 
-This package follows semantic versioning. When making changes:
+This package follows semantic versioning with automated prereleases from `main`:
+
+1. Do not manually bump `package.json` in a feature change.
+2. Merge the validated change to `main`.
+3. The `Prerelease and Publish` workflow runs lint/build checks, increments the prerelease version, publishes it to npm, and creates the matching Git tag.
+4. Consumers must update their dependency and lockfile to the published version before removing any temporary compatibility declarations.
 
-1. Update the version in `package.json`
-2. Create a Git tag for the new version
-3. Push the tag to the repository
+`prepublishOnly` performs a clean build and compiles a consumer against the packed artifact, preventing source-only exports from being published accidentally.
 
 ## Contributing
 
@@ -108,4 +249,4 @@ This package follows semantic versioning. When making changes:
 
 ## License
 
-MIT License - see LICENSE file for details
+MIT License - see LICENSE file for details