@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/types.ts

@@ -1,314 +0,0 @@
-/**
- * HQ Cloud Sync Types
- */
-
-export interface SyncConfig {
-  bucket: string;
-  region: string;
-  userId: string;
-  prefix: string; // e.g. "hq/"
-}
-
-export interface Credentials {
-  accessKeyId: string;
-  secretAccessKey: string;
-  sessionToken?: string;
-  expiration?: string;
-  refreshToken: string;
-  userId: string;
-  bucket: string;
-  region: string;
-  teamId?: string;
-}
-
-export interface JournalEntry {
-  hash: string;
-  size: number;
-  syncedAt: string;
-  direction: "up" | "down";
-  /** Kind of local object represented by this entry. */
-  kind?: "file" | "symlink";
-  /**
-   * Cognito `sub` of the file's author, captured from the object's
-   * `created-by-sub` S3 user-metadata at download time (zero extra network —
-   * the GET response already carries it). Powers the scope-shrink authorship
-   * guard: a scope shrink must never orphan content the caller authored, so
-   * sync mode only ever governs whether you ALSO mirror *other people's*
-   * files. Optional for backwards compatibility — entries written before this
-   * field existed (or uploaded without author metadata) leave it `undefined`,
-   * which the automatic prune path treats conservatively (never auto-delete an
-   * unknown-author orphan).
-   */
-  createdBySub?: string;
-  /**
-   * S3 ETag of the remote object as of last successful sync, normalized (no
-   * surrounding quotes). Optional for backwards compatibility: entries
-   * written before this field existed won't have it, in which case
-   * conflict detection falls back to comparing remote `lastModified`
-   * against `syncedAt`.
-   */
-  remoteEtag?: string;
-  /**
-   * Local mtime (epoch ms) of the file at the moment we last synced it. Used
-   * by the push planner as the fast-path "is this file unchanged?" check:
-   * when `lstat.size === entry.size && lstat.mtimeMs === entry.mtimeMs`,
-   * the SHA256 is skipped and the file is classified `unchanged` without
-   * reading its bytes. Same trade-off rsync/gitignore use — a same-length
-   * edit that doesn't bump mtime will be missed, but that's vanishingly
-   * rare in practice and the speedup on no-op syncs (~5–10×) is the goal.
-   *
-   * Optional for backwards compatibility: entries written before this field
-   * existed (or symlink entries, where lstat.mtimeMs is the link's own
-   * mtime and the prefixed-hash check is already cheap) fall through to
-   * `hashFile()` on the first post-upgrade sync; the next `updateEntry`
-   * stamps the field so subsequent syncs use the fast-path.
-   */
-  mtimeMs?: number;
-  /**
-   * Tombstone marker (Journal v2, US-005). When set, this entry represents
-   * a file that was pruned by a scope shrink — either implicitly (next pull
-   * after the membership's effective scope narrowed) or explicitly (via
-   * `hq sync narrow --apply`). Tombstones are kept for `TOMBSTONE_TTL_MS`
-   * (30d) so subsequent pulls under the same shrunk scope don't re-flag
-   * the same paths as orphans, then garbage-collected.
-   */
-  removedAt?: string;
-  removedReason?: "scope_shrink" | "narrow_apply" | "manual" | "local-delete";
-  /**
-   * Explicit local-delete intent. Unlike the legacy `removedReason` marker,
-   * this is bound to the exact synced remote revision and local object shape
-   * that the user approved for deletion.
-   */
-  localDeleteIntent?: {
-    version: 1;
-    remoteEtag: string;
-    localHash: string;
-    localKind: "file" | "symlink";
-  };
-  /**
-   * Durable automatic-pull retention marker. Set when a scope shrink keeps an
-   * out-of-scope caller-authored or unknown-author entry on disk instead of
-   * pruning it. Subsequent pulls under the already-narrowed scope use this to
-   * exclude the survivor from remote-missing local deletes; it is cleared if
-   * the entry becomes in-scope again.
-   */
-  outOfScopeProtected?: boolean;
-  /**
-   * Journal-honesty marker. Set when a conflict was resolved by KEEPing a local
-   * copy that diverges from the remote: the entry still records the remote
-   * `remoteEtag` (so the conflict can't re-fire — the #137 invariant), but the
-   * local bytes never matched that remote. The currency-gated delete planner
-   * refuses to propagate a delete for such an entry — its currency would
-   * falsely "match" on HEAD, and deleting would destroy the divergent remote
-   * version. Cleared by any genuine download (which makes local == remote).
-   */
-  localDiverges?: boolean;
-}
-
-/**
- * Per-pull boundary record (Journal v2, US-005).
- *
- * Recorded at the end of every per-company sync leg so the next pull can
- * detect "scope changed" against `prefixSet` and compute orphans
- * deterministically. `pulls[]` is append-only; old records are not pruned
- * (cheap, useful for incident forensics — one row per pull per company).
- */
-export interface PullRecord {
-  /** ULID-shaped id (crockford base32, lexically sortable). */
-  pullId: string;
-  companyUid: string;
-  startedAt: string;
-  completedAt: string;
-  /** Effective sync-mode at pull start. */
-  syncMode: "all" | "shared" | "custom";
-  /**
-   * Coalesced prefixes used to drive ListObjectsV2 for this pull. Empty for
-   * v1-migrated records (no recorded scope; treated as full-bucket "all").
-   */
-  prefixSet: string[];
-  scopeChangeDetected: boolean;
-  orphansRemoved: number;
-  orphansBlocked: number;
-}
-
-export interface SyncJournal {
-  /**
-   * Schema version. `"1"` is the pre-US-005 shape (no `pulls`, no
-   * tombstone fields on entries). `"2"` adds per-pull records and
-   * tombstone markers; readers MUST tolerate either and migrate v1 → v2
-   * in place on the first v2 write.
-   */
-  version: "1" | "2";
-  lastSync: string;
-  files: Record<string, JournalEntry>;
-  /**
-   * Per-pull boundary records (v2 only). Always present on v2 journals.
-   * v1 journals do not carry this field — readers should treat absence as
-   * "no recorded history; treat last scope as 'all'/empty".
-   */
-  pulls?: PullRecord[];
-}
-
-/**
- * The legacy v2 journal payload once migrated into the v3 framed state store.
- * The journal shape deliberately stays v2-compatible while its durability and
- * recovery semantics are owned by the v3 snapshot/WAL container.
- */
-export interface V3JournalState {
-  journal: SyncJournal;
-}
-
-/** Payload of the journal's append-only v3 WAL record. */
-export interface V3JournalWalPayload {
-  journal: SyncJournal;
-}
-
-export interface SyncStatus {
-  running: boolean;
-  lastSync: string | null;
-  fileCount: number;
-  bucket: string | null;
-  errors: string[];
-}
-
-export interface PushResult {
-  filesUploaded: number;
-  bytesUploaded: number;
-}
-
-export interface PullResult {
-  filesDownloaded: number;
-  bytesDownloaded: number;
-}
-
-export interface DaemonState {
-  pid: number;
-  startedAt: string;
-  hqRoot: string;
-}
-
-/**
- * Entity-aware context for vault-backed S3 operations (VLT-5).
- * Resolved from vault-service entity registry + STS vending.
- */
-export interface EntityContext {
-  /** Entity UID (cmp_*) */
-  uid: string;
-  /** Entity slug (human-readable, stable key for per-company local state). */
-  slug: string;
-  /** S3 bucket name for this entity */
-  bucketName: string;
-  /** AWS region */
-  region: string;
-  /**
-   * STS-scoped credentials.
-   *
-   * Absent for presign-only COMPANY contexts (HQ-59): when a run uses the
-   * presigned-URL transport for company vaults (`companyVaultUsesPresign`),
-   * `resolveEntityContext` skips the `POST /sts/vend` call entirely — the
-   * presign transport authorizes each object server-side and never reads these
-   * creds, and a compliant sync-runner must NOT hit the company vend route
-   * (the route-presence signal the hq-pro min-version gate keys on). The only
-   * reader of these creds is the direct-S3 (`S3SdkObjectIO`) path, which is
-   * used for personal vaults (`prs_*`, still vended) and pre-presign clients —
-   * never for a `cmp_*` context built on the presign path. That path throws
-   * loudly if it ever receives a credential-less context.
-   */
-  credentials?: VaultCredentials;
-  /**
-   * When the credentials expire (ISO 8601). For a presign-only company context
-   * (no STS vend) this is a far-future sentinel so `isExpiringSoon` is always
-   * false and no auto-refresh ever re-vends the skipped company route.
-   */
-  expiresAt: string;
-}
-
-export interface VaultCredentials {
-  accessKeyId: string;
-  secretAccessKey: string;
-  sessionToken: string;
-}
-
-/**
- * Caller identification stamped on every request to hq-cloud-api so the server
- * can attribute traffic and gate on minimum versions.
- */
-export interface ClientInfo {
-  /** Package name, e.g. "@indigoai-us/hq-cli" */
-  name: string;
-  /** Package version, e.g. "5.15.0" */
-  version: string;
-  /**
-   * `hqVersion` from `core/core.yaml` — set when the caller is running inside
-   * an hq-core checkout. Lets the server see scaffold-generation skew.
-   */
-  hqCoreVersion?: string;
-  /** Arbitrary extra key/value pairs forwarded as `x-hq-client-<key>` headers. */
-  extra?: Record<string, string>;
-}
-
-/**
- * Configuration for connecting to the vault-service API.
- */
-export interface VaultServiceConfig {
-  /** Vault API base URL (e.g. https://vault-api.example.com) */
-  apiUrl: string;
-  /**
-   * Cognito JWT token for authentication. Either a static string OR an async
-   * getter that returns the current token on every call. Long-running consumers
-   * (e.g. `hq-sync-runner`'s multi-company fanout) MUST pass a getter — a
-   * captured string can outlive the 60-min Cognito access token TTL, which
-   * causes mid-flight `refreshEntityContext` calls to 401 against
-   * API Gateway's JWT authorizer even though `~/.hq/cognito-tokens.json` was
-   * refreshed under them by another process (e.g. the menubar). The getter
-   * lets every request resolve the latest token via `getValidAccessToken`.
-   */
-  authToken: string | (() => string | Promise<string>);
-  /** AWS region for S3 client (defaults to entity region or us-east-1) */
-  region?: string;
-  /**
-   * Identifies the calling package + version on every outbound request.
-   * Optional for back-compat, but all first-party clients should pass it.
-   */
-  clientInfo?: ClientInfo;
-  /**
-   * When true, COMPANY vaults (`cmp_*`) use the presigned-URL transport, so
-   * `resolveEntityContext` SKIPS `POST /sts/vend` for them and returns a
-   * credential-less context with a far-future `expiresAt` (HQ-59). Set by the
-   * sync-runner exactly when it installs the presign transport factory, so the
-   * vend-skip and the transport choice can never diverge. Personal vaults
-   * (`prs_*`) are unaffected — they always vend self via `/sts/vend-self`.
-   *
-   * Leaving this unset (the default) preserves the historical behavior: every
-   * context vends STS creds. Non-runner callers (standalone `hq sync`, hq-cli)
-   * that keep the direct-S3 path for company vaults must NOT set this.
-   */
-  companyVaultUsesPresign?: boolean;
-}
-
-// ── Conflict index (consumed by /resolve-conflicts) ─────────────────────────
-//
-// Restored from feat/lineage-conflict-tracking (83bf5fa1) so the producer
-// can write `.conflict-<ts>-<machine>.<ext>` mirror files + append to
-// `<hqRoot>/.hq-conflicts/index.json` whenever the hash-comparison detector
-// flags a conflict that doesn't get overwritten or aborted.
-
-export interface ConflictIndexEntry {
-  id: string;
-  originalPath: string;
-  conflictPath: string;
-  detectedAt: string;
-  side: "push" | "pull";
-  machineId: string;
-  localHash: string;
-  remoteHash: string;
-  /** S3 VersionId when known (present for VersionId-aware buckets). */
-  remoteVersionId?: string;
-  /** Last-known parent VersionId from journal, when known. */
-  lastKnownVersionId?: string | null;
-}
-
-export interface ConflictIndex {
-  version: 1;
-  conflicts: ConflictIndexEntry[];
-}