@cesar-richard/git-connector-sdk 1.57.0 → 1.59.0

package/README.md

@@ -265,6 +265,56 @@ The phrase prefix lets the SDK detect refs even when the number is **bare**
 
 Code blocks (fenced ```` ``` ```` and inline `` ` ``) are stripped before scanning.
 
+### Correlation confidence & billing flags (`attributable`, `resolves`)
+
+Every `linkedActivities[]` entry carries billing-grade correlation metadata so a
+client app can decide, **auditably**, what to impute and how to display issue
+status. All fields are optional (only present once an entity has been
+(re)synced under scoring algo `corr-2026.06`).
+
+| field | type | meaning |
+|---|---|---|
+| `linkKind` | `"reference" \| "resolution" \| "reverse_comment"` | how the link reads: a mention, an explicit closure, or a link discovered from the issue's own comments |
+| `confidence` | `number \| null` | `[0,1]`. Driven by the **form** of the evidence: canonical URL `0.95` > cross-ref (`group/repo#N`) `0.85` > bare short ref `0.78`; `−0.13` in a title, `+0.07` for a resolution verb; ambiguous heuristic-resolved refs capped at `0.60` |
+| `status` | `"confirmed" \| "candidate"` | `confirmed` when `confidence ≥ 0.75` and unambiguous (or confirmed via bidirectional evidence) |
+| `attributable` | `boolean` | **the flag to use for imputation / billing.** `true` ⇔ `status==='confirmed'`, **any** `linkKind`. A PR that merely references an issue (preparatory work) — or is only linked from the issue's comments — still counts as contribution |
+| `resolves` | `boolean` | `true` ⇔ `confirmed && linkKind==='resolution'`. Use for **issue status**, never for billing |
+| `evidence` | `{ field, text, matchStart, matchEnd } \| null` | the matched snippet + offsets, for human audit |
+
+> **Migration note (was `billable`):** the short-lived `billable` field (SDK
+> `1.57.0`) was **removed**. It conflated two questions. Replace it as follows:
+>
+> - imputation / "who worked on this issue" → use **`attributable`** (NOT the
+>   old `billable`, which only fired on closures and missed preparatory work and
+>   reverse-linked PRs);
+> - "what closed the issue" / status → use **`resolves`** (this is what the old
+>   `billable` actually computed).
+
+```ts
+const { data } = await client.GET("/v1/work-items", {
+  params: { query: { state: "open" } },
+});
+for (const wi of data.items) {
+  // Everyone who contributed to this issue (for a CRA / billing sheet):
+  const contributors = new Set(
+    wi.linkedActivities
+      .filter((pr) => pr.attributable)
+      .map((pr) => pr.authorResolved?.login ?? pr.author)
+      .filter(Boolean),
+  );
+
+  // Is the issue actually resolved by a merged PR?
+  const resolved = wi.linkedActivities.some((pr) => pr.resolves && pr.isMerged);
+
+  console.log(`${wi.title}: worked on by [${[...contributors].join(", ")}]`, { resolved });
+}
+```
+
+Two PRs in different repos (e.g. a GitHub PR for terraform groundwork + a GitLab
+MR for the feature) that both reference the same issue both show up as
+`attributable` linked activities on that one work item — that's how cross-repo,
+cross-provider work is consolidated: the issue is the pivot.
+
 ### PR review status (`reviewStatus`)
 
 Each `LinkedActivity` carries an optional `reviewStatus` field with 8 possible

package/dist/schema.d.ts

@@ -281,10 +281,17 @@ export interface components {
                 hintSource: string;
                 kind: string;
             };
+            /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
             linkKind?: string;
+            /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
             confidence?: number | null;
+            /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
             status?: string;
-            billable?: boolean;
+            /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+            attributable?: boolean;
+            /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+            resolves?: boolean;
+            /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
             evidence?: {
                 field: string;
                 text: string;
@@ -461,10 +468,17 @@ export interface components {
                     hintSource: string;
                     kind: string;
                 };
+                /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                 linkKind?: string;
+                /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                 confidence?: number | null;
+                /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                 status?: string;
-                billable?: boolean;
+                /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                attributable?: boolean;
+                /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                resolves?: boolean;
+                /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                 evidence?: {
                     field: string;
                     text: string;
@@ -592,10 +606,17 @@ export interface components {
                         hintSource: string;
                         kind: string;
                     };
+                    /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                     linkKind?: string;
+                    /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                     confidence?: number | null;
+                    /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                     status?: string;
-                    billable?: boolean;
+                    /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                    attributable?: boolean;
+                    /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                    resolves?: boolean;
+                    /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                     evidence?: {
                         field: string;
                         text: string;
@@ -772,10 +793,17 @@ export interface operations {
                                     hintSource: string;
                                     kind: string;
                                 };
+                                /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                                 linkKind?: string;
+                                /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                                 confidence?: number | null;
+                                /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                                 status?: string;
-                                billable?: boolean;
+                                /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                                attributable?: boolean;
+                                /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                                resolves?: boolean;
+                                /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                                 evidence?: {
                                     field: string;
                                     text: string;
@@ -907,10 +935,17 @@ export interface operations {
                                     hintSource: string;
                                     kind: string;
                                 };
+                                /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                                 linkKind?: string;
+                                /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                                 confidence?: number | null;
+                                /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                                 status?: string;
-                                billable?: boolean;
+                                /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                                attributable?: boolean;
+                                /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                                resolves?: boolean;
+                                /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                                 evidence?: {
                                     field: string;
                                     text: string;
@@ -1042,10 +1077,17 @@ export interface operations {
                                     hintSource: string;
                                     kind: string;
                                 };
+                                /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                                 linkKind?: string;
+                                /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                                 confidence?: number | null;
+                                /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                                 status?: string;
-                                billable?: boolean;
+                                /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                                attributable?: boolean;
+                                /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                                resolves?: boolean;
+                                /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                                 evidence?: {
                                     field: string;
                                     text: string;
@@ -1201,10 +1243,17 @@ export interface operations {
                                 hintSource: string;
                                 kind: string;
                             };
+                            /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                             linkKind?: string;
+                            /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                             confidence?: number | null;
+                            /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                             status?: string;
-                            billable?: boolean;
+                            /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                            attributable?: boolean;
+                            /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                            resolves?: boolean;
+                            /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                             evidence?: {
                                 field: string;
                                 text: string;
@@ -1331,10 +1380,17 @@ export interface operations {
                                 hintSource: string;
                                 kind: string;
                             };
+                            /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                             linkKind?: string;
+                            /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                             confidence?: number | null;
+                            /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                             status?: string;
-                            billable?: boolean;
+                            /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                            attributable?: boolean;
+                            /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                            resolves?: boolean;
+                            /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                             evidence?: {
                                 field: string;
                                 text: string;
@@ -1461,10 +1517,17 @@ export interface operations {
                                 hintSource: string;
                                 kind: string;
                             };
+                            /** @description Raw link classification: 'reference' (mention), 'resolution' (closes the issue), or 'reverse_comment' (link discovered from the issue's comments pointing back at this PR/MR). */
                             linkKind?: string;
+                            /** @description Deterministic correlation confidence in [0,1]. Driven by the form of the evidence (canonical URL > cross-ref > bare short ref), with a title penalty and a resolution bonus. Ambiguous heuristic-resolved refs are capped at 0.60. */
                             confidence?: number | null;
+                            /** @description 'confirmed' when confidence >= 0.75 and the link is unambiguous (or confirmed via bidirectional evidence); otherwise 'candidate'. Only 'confirmed' links are attributable. */
                             status?: string;
-                            billable?: boolean;
+                            /** @description True when the linked PR/MR CONTRIBUTED to the issue (status === 'confirmed', any linkKind incl. references and reverse links). This is the flag to use for imputation/billing — preparatory work counts. */
+                            attributable?: boolean;
+                            /** @description True when the linked PR/MR actually CLOSES the issue (status === 'confirmed' && linkKind === 'resolution'). Use for issue status, NOT for billing. */
+                            resolves?: boolean;
+                            /** @description Audit trail: the matched snippet, the field it was found in, and the offsets — so a human can verify why the link was classified this way. */
                             evidence?: {
                                 field: string;
                                 text: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesar-richard/git-connector-sdk",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "TypeScript SDK for the git-connector v1 API (work items + iterations aggregated from GitHub/GitLab). Version published on npm tracks server releases.",
   "license": "MIT",
   "repository": {