@knpkv/jcf-web 0.2.0

package/dist/shared/contracts.d.ts

@@ -0,0 +1,901 @@
+/**
+ * The HTTP contract of the week view.
+ *
+ * **Mental model**
+ *
+ * - **Reads and reviewed writes.** `week` shows what each system holds, what the sessions say is
+ *   missing, and what could not be placed. Description suggestions reuse that scan's evidence;
+ *   confirmation, manual entry and saved-entry update requests write provider time.
+ * - **The server owns expected state.** Confirmations name retained row evidence. Saved-entry edits
+ *   name a retained provider entry; the engine rechecks that snapshot before updating it.
+ * - **Edits are explicit.** Confirmations may override amount, Issue Key and note. Saved-entry edits
+ *   change time and exact description. Generating a description never saves it.
+ *
+ * @module
+ */
+import { Schema } from "effect";
+/** A local calendar day, `YYYY-MM-DD` — the unit every bucket in jcf is keyed by. */
+export declare const Day: Schema.String;
+/**
+ * An Issue Key as Jira writes them. Checked here as well as in the engine so a malformed override
+ * is refused at the boundary, before it can become a Clockify description nothing can read back.
+ */
+export declare const TicketKey: Schema.String;
+/** Seconds of work: whole, positive, and under a day. */
+export declare const WorkSeconds: Schema.Number;
+/** Free text a person typed, bounded so a description cannot be used to write a novel into Jira. */
+export declare const Note: Schema.String;
+/** Request a row-level note from the scan's retained evidence, without reading sessions again. */
+export declare const DescribeRowRequest: Schema.Struct<{
+    readonly planId: Schema.String;
+    readonly rowId: Schema.String;
+}>;
+export interface DescribeRowRequest extends Schema.Schema.Type<typeof DescribeRowRequest> {
+}
+/** A suggestion for review, never an instruction to write it to a provider. */
+export declare const DescribeRowResponse: Schema.Struct<{
+    readonly planId: Schema.String;
+    readonly rowId: Schema.String;
+    readonly note: Schema.NullOr<Schema.String>;
+}>;
+export interface DescribeRowResponse extends Schema.Schema.Type<typeof DescribeRowResponse> {
+}
+/** Whole provider entry, retained on every visible slice. Description includes provider prefixes. */
+export declare const SavedEntry: Schema.Struct<{
+    /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+    readonly revision: Schema.String;
+    readonly id: Schema.String;
+    readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+    readonly ticketKey: Schema.NullOr<Schema.String>;
+    readonly startMs: Schema.Number;
+    readonly endMs: Schema.Number;
+    readonly description: Schema.NullOr<Schema.String>;
+}>;
+export interface SavedEntry extends Schema.Schema.Type<typeof SavedEntry> {
+}
+export declare const DescribeSavedEntryRequest: Schema.Struct<{
+    readonly planId: Schema.String;
+    readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+    readonly entryId: Schema.String;
+}>;
+export interface DescribeSavedEntryRequest extends Schema.Schema.Type<typeof DescribeSavedEntryRequest> {
+}
+export declare const DescribeSavedEntryResponse: Schema.Struct<{
+    readonly planId: Schema.String;
+    readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+    readonly entryId: Schema.String;
+    readonly note: Schema.NullOr<Schema.String>;
+    readonly sessionCount: Schema.Number;
+}>;
+export interface DescribeSavedEntryResponse extends Schema.Schema.Type<typeof DescribeSavedEntryResponse> {
+}
+/** Server resolves the expected entry; the client can change only its interval and exact description. */
+export declare const UpdateSavedEntryRequest: Schema.Struct<{
+    readonly planId: Schema.String;
+    readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+    readonly entryId: Schema.String;
+    readonly revision: Schema.String;
+    readonly startMs: Schema.Number;
+    readonly endMs: Schema.Number;
+    readonly description: Schema.String;
+}>;
+export interface UpdateSavedEntryRequest extends Schema.Schema.Type<typeof UpdateSavedEntryRequest> {
+}
+export declare const UpdateSavedEntryResponse: Schema.Struct<{
+    readonly planId: Schema.String;
+    readonly entry: Schema.Struct<{
+        /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+        readonly revision: Schema.String;
+        readonly id: Schema.String;
+        readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+        readonly ticketKey: Schema.NullOr<Schema.String>;
+        readonly startMs: Schema.Number;
+        readonly endMs: Schema.Number;
+        readonly description: Schema.NullOr<Schema.String>;
+    }>;
+}>;
+export interface UpdateSavedEntryResponse extends Schema.Schema.Type<typeof UpdateSavedEntryResponse> {
+}
+declare const ApiError_base: Schema.Class<ApiError, Schema.TaggedStruct<"ApiError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ApiError extends ApiError_base {
+}
+declare const UnauthorizedApiError_base: Schema.Class<UnauthorizedApiError, Schema.TaggedStruct<"UnauthorizedApiError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnauthorizedApiError extends UnauthorizedApiError_base {
+}
+declare const ForbiddenApiError_base: Schema.Class<ForbiddenApiError, Schema.TaggedStruct<"ForbiddenApiError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ForbiddenApiError extends ForbiddenApiError_base {
+}
+declare const PlanExpiredError_base: Schema.Class<PlanExpiredError, Schema.TaggedStruct<"PlanExpiredError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The plan a confirmation names is gone, or the row in it is.
+ *
+ * Separate from a rejected write because the repair is different and the browser can do it without
+ * asking anyone: re-read the week and offer the row again.
+ */
+export declare class PlanExpiredError extends PlanExpiredError_base {
+}
+declare const ProposalRejectedError_base: Schema.Class<ProposalRejectedError, Schema.TaggedStruct<"ProposalRejectedError", {
+    readonly message: Schema.String;
+    readonly maxSeconds: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The write was refused on its own terms — an amount past what the evidence supports, an Issue Key
+ * the engine will not write. `maxSeconds` is present when a cap is what refused it, so the browser
+ * can say what the ceiling is rather than only that there is one.
+ */
+export declare class ProposalRejectedError extends ProposalRejectedError_base {
+}
+/**
+ * One stretch of credited work: when it happened, and what it is worth.
+ *
+ * Epoch milliseconds because the browser draws these on a grid, and `seconds` because a block is
+ * what a person accepts on its own — `seconds` is its share of the row, which on time worked in
+ * parallel is less than the interval it spans.
+ */
+export declare const ProposalBlock: Schema.Struct<{
+    /** Normalized seconds this source block already supplied to each provider, including corrected-ticket writes. */
+    readonly consumed: Schema.Struct<{
+        readonly clockify: Schema.Number;
+        readonly jira: Schema.Number;
+    }>;
+    /** A provider-specific safety hold, never a consumed-seconds estimate. */
+    readonly clockifyRefusal: Schema.optionalKey<Schema.Literal<"unlinked-overlap">>;
+    readonly endMs: Schema.Number;
+    readonly seconds: Schema.Number;
+    readonly startMs: Schema.Number;
+    /** Stable source-cluster identity; rendered starts may move as overlapping work grows. */
+    readonly sourceStartMs: Schema.optional<Schema.Number>;
+}>;
+/** Which evidence placed a row on its Issue Key. */
+export declare const AttributionSignal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+/**
+ * Which systems a week is about.
+ *
+ * One name rather than two booleans in the query string, because "neither" is not a week anyone
+ * asked for. A side that is out is not read, not proposed for, and not written to — so a week with
+ * `only=jira` never touches Clockify at all.
+ */
+export declare const WeekScope: Schema.Literals<readonly ["both", "clockify", "jira"]>;
+/** Which systems a single write may touch. Defaults to the scope the week was read under. */
+export declare const WriteTargets: Schema.Struct<{
+    readonly clockify: Schema.Boolean;
+    readonly jira: Schema.Boolean;
+}>;
+/** When recorded time happened, and which system says so. */
+export declare const RecordedInterval: Schema.Struct<{
+    readonly entry: Schema.optionalKey<Schema.Struct<{
+        /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+        readonly revision: Schema.String;
+        readonly id: Schema.String;
+        readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+        readonly ticketKey: Schema.NullOr<Schema.String>;
+        readonly startMs: Schema.Number;
+        readonly endMs: Schema.Number;
+        readonly description: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly endMs: Schema.Number;
+    readonly source: Schema.Literals<readonly ["clockify", "jira"]>;
+    readonly startMs: Schema.Number;
+}>;
+/**
+ * What a row's sessions say, and what accepting it would write.
+ *
+ * `maxSeconds` is the credited evidence: the ceiling on an edited amount. Editing below it is a
+ * person saying the evidence overstates the work; editing above it would be the tool inventing
+ * hours, which is the one thing every rule here exists to prevent.
+ */
+export declare const RowProposal: Schema.Struct<{
+    readonly activeSeconds: Schema.Number;
+    /**
+     * The stretches behind this row, ascending. They sum to `maxSeconds`, and a confirmation may name
+     * a subset of them by position — which is how a morning gets written without the afternoon.
+     */
+    readonly blocks: Schema.$Array<Schema.Struct<{
+        /** Normalized seconds this source block already supplied to each provider, including corrected-ticket writes. */
+        readonly consumed: Schema.Struct<{
+            readonly clockify: Schema.Number;
+            readonly jira: Schema.Number;
+        }>;
+        /** A provider-specific safety hold, never a consumed-seconds estimate. */
+        readonly clockifyRefusal: Schema.optionalKey<Schema.Literal<"unlinked-overlap">>;
+        readonly endMs: Schema.Number;
+        readonly seconds: Schema.Number;
+        readonly startMs: Schema.Number;
+        /** Stable source-cluster identity; rendered starts may move as overlapping work grows. */
+        readonly sourceStartMs: Schema.optional<Schema.Number>;
+    }>>;
+    readonly clockifyDelta: Schema.Number;
+    readonly confidence: Schema.NullOr<Schema.Number>;
+    readonly jiraDelta: Schema.Number;
+    readonly maxSeconds: Schema.Number;
+    readonly sessionCount: Schema.Number;
+    readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+}>;
+/**
+ * One `(Issue Key, day)` cell of the week.
+ *
+ * Rows exist for time that is only recorded, only evidenced, or both — a day tracked with a Timer
+ * has no proposal, and a day nobody logged has no allocated seconds. Which is the point of showing
+ * them together.
+ */
+export declare const WeekRow: Schema.Struct<{
+    readonly clockifyDescription: Schema.NullOr<Schema.String>;
+    readonly clockifySeconds: Schema.Number;
+    readonly day: Schema.String;
+    /**
+     * When the recorded time happened — the entries behind the totals, so a week can be drawn as a
+     * calendar. Empty when the systems reported no usable interval, never fabricated from the total.
+     */
+    readonly intervals: Schema.$Array<Schema.Struct<{
+        readonly entry: Schema.optionalKey<Schema.Struct<{
+            /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+            readonly revision: Schema.String;
+            readonly id: Schema.String;
+            readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+            readonly ticketKey: Schema.NullOr<Schema.String>;
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+            readonly description: Schema.NullOr<Schema.String>;
+        }>>;
+        readonly endMs: Schema.Number;
+        readonly source: Schema.Literals<readonly ["clockify", "jira"]>;
+        readonly startMs: Schema.Number;
+    }>>;
+    readonly jiraSeconds: Schema.Number;
+    readonly proposal: Schema.optional<Schema.Struct<{
+        readonly activeSeconds: Schema.Number;
+        /**
+         * The stretches behind this row, ascending. They sum to `maxSeconds`, and a confirmation may name
+         * a subset of them by position — which is how a morning gets written without the afternoon.
+         */
+        readonly blocks: Schema.$Array<Schema.Struct<{
+            /** Normalized seconds this source block already supplied to each provider, including corrected-ticket writes. */
+            readonly consumed: Schema.Struct<{
+                readonly clockify: Schema.Number;
+                readonly jira: Schema.Number;
+            }>;
+            /** A provider-specific safety hold, never a consumed-seconds estimate. */
+            readonly clockifyRefusal: Schema.optionalKey<Schema.Literal<"unlinked-overlap">>;
+            readonly endMs: Schema.Number;
+            readonly seconds: Schema.Number;
+            readonly startMs: Schema.Number;
+            /** Stable source-cluster identity; rendered starts may move as overlapping work grows. */
+            readonly sourceStartMs: Schema.optional<Schema.Number>;
+        }>>;
+        readonly clockifyDelta: Schema.Number;
+        readonly confidence: Schema.NullOr<Schema.Number>;
+        readonly jiraDelta: Schema.Number;
+        readonly maxSeconds: Schema.Number;
+        readonly sessionCount: Schema.Number;
+        readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+    }>>;
+    readonly rowId: Schema.String;
+    readonly ticketKey: Schema.String;
+    /**
+     * The issue title, or null when Jira could not be asked — logged out, unreachable, or out of
+     * scope for this week. Null is "unknown", never "untitled": an Issue Key alone is a lookup nobody
+     * can do six months later, so it is worth saying when it is missing.
+     */
+    readonly ticketTitle: Schema.NullOr<Schema.String>;
+}>;
+/** Hours that happened on a day and no signal could place, with the directories behind them. */
+export declare const UnattributedDay: Schema.Struct<{
+    readonly cwds: Schema.$Array<Schema.String>;
+    readonly day: Schema.String;
+    readonly seconds: Schema.Number;
+    readonly sessionCount: Schema.Number;
+}>;
+/** Attributed by a Coding Agent below the confidence floor: shown so the hours stay visible. */
+export declare const WithheldRow: Schema.Struct<{
+    readonly confidence: Schema.NullOr<Schema.Number>;
+    readonly day: Schema.String;
+    readonly seconds: Schema.Number;
+    readonly ticketKey: Schema.String;
+    readonly ticketTitle: Schema.NullOr<Schema.String>;
+}>;
+/**
+ * Hours a signal placed on a ticket Jira says belongs to somebody else.
+ *
+ * Reported rather than proposed, and reported rather than dropped: a branch cannot tell authoring
+ * from reviewing, so this is usually a pull request you read — and occasionally your own work on a
+ * colleague's ticket, which is what `assignee` and the override are for.
+ */
+export declare const NotMineRow: Schema.Struct<{
+    /** Who Jira says owns it, or null when it is unassigned. */
+    readonly assignee: Schema.NullOr<Schema.String>;
+    readonly day: Schema.String;
+    readonly seconds: Schema.Number;
+    readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+    readonly ticketKey: Schema.String;
+    readonly ticketTitle: Schema.NullOr<Schema.String>;
+}>;
+/** A day withheld from proposals, with the reason, so it never reads as "nothing to log". */
+export declare const ExcludedDay: Schema.Struct<{
+    readonly day: Schema.String;
+    readonly reason: Schema.String;
+}>;
+export declare const WeekPlan: Schema.Struct<{
+    /**
+     * True when a Coding Agent was needed and could not be reached. The deterministic rows are still
+     * complete; what is missing is only the placement of sessions no branch or path could place.
+     */
+    readonly attributorAvailable: Schema.Boolean;
+    readonly attributorCalls: Schema.Number;
+    readonly days: Schema.$Array<Schema.String>;
+    readonly excludedDays: Schema.$Array<Schema.Struct<{
+        readonly day: Schema.String;
+        readonly reason: Schema.String;
+    }>>;
+    readonly monday: Schema.String;
+    /** Names the server-held evidence a confirmation refers to. */
+    readonly planId: Schema.String;
+    readonly rows: Schema.$Array<Schema.Struct<{
+        readonly clockifyDescription: Schema.NullOr<Schema.String>;
+        readonly clockifySeconds: Schema.Number;
+        readonly day: Schema.String;
+        /**
+         * When the recorded time happened — the entries behind the totals, so a week can be drawn as a
+         * calendar. Empty when the systems reported no usable interval, never fabricated from the total.
+         */
+        readonly intervals: Schema.$Array<Schema.Struct<{
+            readonly entry: Schema.optionalKey<Schema.Struct<{
+                /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+                readonly revision: Schema.String;
+                readonly id: Schema.String;
+                readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+                readonly ticketKey: Schema.NullOr<Schema.String>;
+                readonly startMs: Schema.Number;
+                readonly endMs: Schema.Number;
+                readonly description: Schema.NullOr<Schema.String>;
+            }>>;
+            readonly endMs: Schema.Number;
+            readonly source: Schema.Literals<readonly ["clockify", "jira"]>;
+            readonly startMs: Schema.Number;
+        }>>;
+        readonly jiraSeconds: Schema.Number;
+        readonly proposal: Schema.optional<Schema.Struct<{
+            readonly activeSeconds: Schema.Number;
+            /**
+             * The stretches behind this row, ascending. They sum to `maxSeconds`, and a confirmation may name
+             * a subset of them by position — which is how a morning gets written without the afternoon.
+             */
+            readonly blocks: Schema.$Array<Schema.Struct<{
+                /** Normalized seconds this source block already supplied to each provider, including corrected-ticket writes. */
+                readonly consumed: Schema.Struct<{
+                    readonly clockify: Schema.Number;
+                    readonly jira: Schema.Number;
+                }>;
+                /** A provider-specific safety hold, never a consumed-seconds estimate. */
+                readonly clockifyRefusal: Schema.optionalKey<Schema.Literal<"unlinked-overlap">>;
+                readonly endMs: Schema.Number;
+                readonly seconds: Schema.Number;
+                readonly startMs: Schema.Number;
+                /** Stable source-cluster identity; rendered starts may move as overlapping work grows. */
+                readonly sourceStartMs: Schema.optional<Schema.Number>;
+            }>>;
+            readonly clockifyDelta: Schema.Number;
+            readonly confidence: Schema.NullOr<Schema.Number>;
+            readonly jiraDelta: Schema.Number;
+            readonly maxSeconds: Schema.Number;
+            readonly sessionCount: Schema.Number;
+            readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+        }>>;
+        readonly rowId: Schema.String;
+        readonly ticketKey: Schema.String;
+        /**
+         * The issue title, or null when Jira could not be asked — logged out, unreachable, or out of
+         * scope for this week. Null is "unknown", never "untitled": an Issue Key alone is a lookup nobody
+         * can do six months later, so it is worth saying when it is missing.
+         */
+        readonly ticketTitle: Schema.NullOr<Schema.String>;
+    }>>;
+    /** Closed Clockify entries without a ticket, excluded from ticket reconciliation. */
+    readonly unlinkedClockify: Schema.$Array<Schema.Struct<{
+        readonly entry: Schema.optionalKey<Schema.Struct<{
+            /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+            readonly revision: Schema.String;
+            readonly id: Schema.String;
+            readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+            readonly ticketKey: Schema.NullOr<Schema.String>;
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+            readonly description: Schema.NullOr<Schema.String>;
+        }>>;
+        readonly day: Schema.String;
+        readonly seconds: Schema.Number;
+        readonly description: Schema.NullOr<Schema.String>;
+        readonly startMs: Schema.Number;
+        readonly endMs: Schema.Number;
+    }>>;
+    readonly sessionCount: Schema.Number;
+    /** False for recorded-only weeks. Omitted by older servers means a session scan is available. */
+    readonly sessionScanAvailable: Schema.optional<Schema.Boolean>;
+    /** Which systems this week was read from. A side that is out reports zero because nobody asked. */
+    readonly scope: Schema.Literals<readonly ["both", "clockify", "jira"]>;
+    /** Zero means nothing is opted in, which is the usual reason for an empty week. */
+    readonly sessionRootCount: Schema.Number;
+    /** Hours on tickets assigned to somebody else. Empty when ownership is not being enforced. */
+    readonly notMine: Schema.$Array<Schema.Struct<{
+        /** Who Jira says owns it, or null when it is unassigned. */
+        readonly assignee: Schema.NullOr<Schema.String>;
+        readonly day: Schema.String;
+        readonly seconds: Schema.Number;
+        readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+        readonly ticketKey: Schema.String;
+        readonly ticketTitle: Schema.NullOr<Schema.String>;
+    }>>;
+    /**
+     * True when Jira actually answered about who owns these tickets.
+     *
+     * False means nothing was filtered on ownership, whatever the setting says — a week that quietly
+     * hid rows because Jira was unreachable would be a week missing hours with nothing to explain it.
+     */
+    readonly ownershipChecked: Schema.Boolean;
+    /** Whether this week withheld tickets assigned to other people. */
+    readonly ownership: Schema.Literals<readonly ["assigned", "any"]>;
+    readonly unattributed: Schema.$Array<Schema.Struct<{
+        readonly cwds: Schema.$Array<Schema.String>;
+        readonly day: Schema.String;
+        readonly seconds: Schema.Number;
+        readonly sessionCount: Schema.Number;
+    }>>;
+    readonly withheld: Schema.$Array<Schema.Struct<{
+        readonly confidence: Schema.NullOr<Schema.Number>;
+        readonly day: Schema.String;
+        readonly seconds: Schema.Number;
+        readonly ticketKey: Schema.String;
+        readonly ticketTitle: Schema.NullOr<Schema.String>;
+    }>>;
+}>;
+/** Authenticated cached view. Missing evidence allows provider-only reads; suggestions require an explicit scan. */
+export declare const SavedWeek: Schema.Struct<{
+    readonly monday: Schema.String;
+    readonly scope: Schema.Literals<readonly ["both", "clockify", "jira"]>;
+    readonly plan: Schema.NullOr<Schema.Struct<{
+        /**
+         * True when a Coding Agent was needed and could not be reached. The deterministic rows are still
+         * complete; what is missing is only the placement of sessions no branch or path could place.
+         */
+        readonly attributorAvailable: Schema.Boolean;
+        readonly attributorCalls: Schema.Number;
+        readonly days: Schema.$Array<Schema.String>;
+        readonly excludedDays: Schema.$Array<Schema.Struct<{
+            readonly day: Schema.String;
+            readonly reason: Schema.String;
+        }>>;
+        readonly monday: Schema.String;
+        /** Names the server-held evidence a confirmation refers to. */
+        readonly planId: Schema.String;
+        readonly rows: Schema.$Array<Schema.Struct<{
+            readonly clockifyDescription: Schema.NullOr<Schema.String>;
+            readonly clockifySeconds: Schema.Number;
+            readonly day: Schema.String;
+            /**
+             * When the recorded time happened — the entries behind the totals, so a week can be drawn as a
+             * calendar. Empty when the systems reported no usable interval, never fabricated from the total.
+             */
+            readonly intervals: Schema.$Array<Schema.Struct<{
+                readonly entry: Schema.optionalKey<Schema.Struct<{
+                    /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+                    readonly revision: Schema.String;
+                    readonly id: Schema.String;
+                    readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+                    readonly ticketKey: Schema.NullOr<Schema.String>;
+                    readonly startMs: Schema.Number;
+                    readonly endMs: Schema.Number;
+                    readonly description: Schema.NullOr<Schema.String>;
+                }>>;
+                readonly endMs: Schema.Number;
+                readonly source: Schema.Literals<readonly ["clockify", "jira"]>;
+                readonly startMs: Schema.Number;
+            }>>;
+            readonly jiraSeconds: Schema.Number;
+            readonly proposal: Schema.optional<Schema.Struct<{
+                readonly activeSeconds: Schema.Number;
+                /**
+                 * The stretches behind this row, ascending. They sum to `maxSeconds`, and a confirmation may name
+                 * a subset of them by position — which is how a morning gets written without the afternoon.
+                 */
+                readonly blocks: Schema.$Array<Schema.Struct<{
+                    /** Normalized seconds this source block already supplied to each provider, including corrected-ticket writes. */
+                    readonly consumed: Schema.Struct<{
+                        readonly clockify: Schema.Number;
+                        readonly jira: Schema.Number;
+                    }>;
+                    /** A provider-specific safety hold, never a consumed-seconds estimate. */
+                    readonly clockifyRefusal: Schema.optionalKey<Schema.Literal<"unlinked-overlap">>;
+                    readonly endMs: Schema.Number;
+                    readonly seconds: Schema.Number;
+                    readonly startMs: Schema.Number;
+                    /** Stable source-cluster identity; rendered starts may move as overlapping work grows. */
+                    readonly sourceStartMs: Schema.optional<Schema.Number>;
+                }>>;
+                readonly clockifyDelta: Schema.Number;
+                readonly confidence: Schema.NullOr<Schema.Number>;
+                readonly jiraDelta: Schema.Number;
+                readonly maxSeconds: Schema.Number;
+                readonly sessionCount: Schema.Number;
+                readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+            }>>;
+            readonly rowId: Schema.String;
+            readonly ticketKey: Schema.String;
+            /**
+             * The issue title, or null when Jira could not be asked — logged out, unreachable, or out of
+             * scope for this week. Null is "unknown", never "untitled": an Issue Key alone is a lookup nobody
+             * can do six months later, so it is worth saying when it is missing.
+             */
+            readonly ticketTitle: Schema.NullOr<Schema.String>;
+        }>>;
+        /** Closed Clockify entries without a ticket, excluded from ticket reconciliation. */
+        readonly unlinkedClockify: Schema.$Array<Schema.Struct<{
+            readonly entry: Schema.optionalKey<Schema.Struct<{
+                /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+                readonly revision: Schema.String;
+                readonly id: Schema.String;
+                readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+                readonly ticketKey: Schema.NullOr<Schema.String>;
+                readonly startMs: Schema.Number;
+                readonly endMs: Schema.Number;
+                readonly description: Schema.NullOr<Schema.String>;
+            }>>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly description: Schema.NullOr<Schema.String>;
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+        }>>;
+        readonly sessionCount: Schema.Number;
+        /** False for recorded-only weeks. Omitted by older servers means a session scan is available. */
+        readonly sessionScanAvailable: Schema.optional<Schema.Boolean>;
+        /** Which systems this week was read from. A side that is out reports zero because nobody asked. */
+        readonly scope: Schema.Literals<readonly ["both", "clockify", "jira"]>;
+        /** Zero means nothing is opted in, which is the usual reason for an empty week. */
+        readonly sessionRootCount: Schema.Number;
+        /** Hours on tickets assigned to somebody else. Empty when ownership is not being enforced. */
+        readonly notMine: Schema.$Array<Schema.Struct<{
+            /** Who Jira says owns it, or null when it is unassigned. */
+            readonly assignee: Schema.NullOr<Schema.String>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+            readonly ticketKey: Schema.String;
+            readonly ticketTitle: Schema.NullOr<Schema.String>;
+        }>>;
+        /**
+         * True when Jira actually answered about who owns these tickets.
+         *
+         * False means nothing was filtered on ownership, whatever the setting says — a week that quietly
+         * hid rows because Jira was unreachable would be a week missing hours with nothing to explain it.
+         */
+        readonly ownershipChecked: Schema.Boolean;
+        /** Whether this week withheld tickets assigned to other people. */
+        readonly ownership: Schema.Literals<readonly ["assigned", "any"]>;
+        readonly unattributed: Schema.$Array<Schema.Struct<{
+            readonly cwds: Schema.$Array<Schema.String>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly sessionCount: Schema.Number;
+        }>>;
+        readonly withheld: Schema.$Array<Schema.Struct<{
+            readonly confidence: Schema.NullOr<Schema.Number>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly ticketKey: Schema.String;
+            readonly ticketTitle: Schema.NullOr<Schema.String>;
+        }>>;
+    }>>;
+}>;
+/** What one side of a write did. Mirrors `SideOutcome` in the engine. */
+export declare const SideOutcome: Schema.Union<readonly [Schema.TaggedStruct<"Written", {
+    readonly seconds: Schema.Number;
+    readonly segments: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly startMs: Schema.Number;
+        readonly endMs: Schema.Number;
+    }>>>;
+}>, Schema.TaggedStruct<"PartiallyWritten", {
+    readonly seconds: Schema.Number;
+    readonly segments: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly startMs: Schema.Number;
+        readonly endMs: Schema.Number;
+    }>>>;
+    readonly failure: Schema.Union<readonly [Schema.TaggedStruct<"Refused", {
+        readonly message: Schema.String;
+    }>, Schema.TaggedStruct<"NotLoggedIn", {}>]>;
+}>, Schema.TaggedStruct<"NothingOwed", {}>, Schema.TaggedStruct<"Skipped", {}>, Schema.TaggedStruct<"Refused", {
+    readonly message: Schema.String;
+}>, Schema.TaggedStruct<"NotLoggedIn", {}>]>;
+/**
+ * What a write actually did, in the engine's own words.
+ *
+ * `lines` is rendered by the engine rather than the browser so a terminal and a page cannot describe
+ * the same write differently. `description` is what landed in both systems, returned because it is
+ * the text other people will read.
+ */
+export declare const WriteResult: Schema.Struct<{
+    readonly clockify: Schema.Union<readonly [Schema.TaggedStruct<"Written", {
+        readonly seconds: Schema.Number;
+        readonly segments: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+        }>>>;
+    }>, Schema.TaggedStruct<"PartiallyWritten", {
+        readonly seconds: Schema.Number;
+        readonly segments: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+        }>>>;
+        readonly failure: Schema.Union<readonly [Schema.TaggedStruct<"Refused", {
+            readonly message: Schema.String;
+        }>, Schema.TaggedStruct<"NotLoggedIn", {}>]>;
+    }>, Schema.TaggedStruct<"NothingOwed", {}>, Schema.TaggedStruct<"Skipped", {}>, Schema.TaggedStruct<"Refused", {
+        readonly message: Schema.String;
+    }>, Schema.TaggedStruct<"NotLoggedIn", {}>]>;
+    readonly description: Schema.String;
+    readonly jira: Schema.Union<readonly [Schema.TaggedStruct<"Written", {
+        readonly seconds: Schema.Number;
+        readonly segments: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+        }>>>;
+    }>, Schema.TaggedStruct<"PartiallyWritten", {
+        readonly seconds: Schema.Number;
+        readonly segments: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+        }>>>;
+        readonly failure: Schema.Union<readonly [Schema.TaggedStruct<"Refused", {
+            readonly message: Schema.String;
+        }>, Schema.TaggedStruct<"NotLoggedIn", {}>]>;
+    }>, Schema.TaggedStruct<"NothingOwed", {}>, Schema.TaggedStruct<"Skipped", {}>, Schema.TaggedStruct<"Refused", {
+        readonly message: Schema.String;
+    }>, Schema.TaggedStruct<"NotLoggedIn", {}>]>;
+    readonly lines: Schema.$Array<Schema.String>;
+}>;
+/**
+ * Accept one proposed row, optionally with the amount or the Issue Key overruled.
+ *
+ * No spans, no credited seconds, no deltas: the server holds the evidence this row was built from
+ * and re-reads both systems before writing, so the only numbers a browser can influence are the ones
+ * a person is allowed to choose.
+ */
+export declare const ConfirmPayload: Schema.Struct<{
+    /**
+     * Which of the row's blocks to write, by position. Absent means all of them.
+     *
+     * Positions rather than times or durations, so the server still owns every number: naming block
+     * two of a row it built is not the same kind of claim as sending "40 minutes at 20:52".
+     */
+    readonly blocks: Schema.optional<Schema.$Array<Schema.Number>>;
+    readonly note: Schema.optional<Schema.String>;
+    readonly planId: Schema.String;
+    readonly rowId: Schema.String;
+    /** Absent means the systems the week was read under. Neither is a usage error, not a write. */
+    readonly targets: Schema.optional<Schema.Struct<{
+        readonly clockify: Schema.Boolean;
+        readonly jira: Schema.Boolean;
+    }>>;
+    /** Absent means "as proposed". Present must not exceed the row's `maxSeconds`. */
+    readonly seconds: Schema.optional<Schema.Number>;
+    /** Absent means the Issue Key the evidence placed it on. */
+    readonly ticketKey: Schema.optional<Schema.String>;
+}>;
+/**
+ * Log time no session evidences — a meeting, a whiteboard, a review away from the keyboard.
+ *
+ * Deliberately an *addition* rather than a top-up: a person typing 30 minutes means add 30 minutes,
+ * which is what `jcf timer log` has always done. Nothing is subtracted, so running it twice logs
+ * twice, exactly as typing it twice would.
+ */
+export declare const ManualPayload: Schema.Struct<{
+    readonly day: Schema.String;
+    readonly note: Schema.optional<Schema.String>;
+    readonly seconds: Schema.Number;
+    readonly targets: Schema.optional<Schema.Struct<{
+        readonly clockify: Schema.Boolean;
+        readonly jira: Schema.Boolean;
+    }>>;
+    /** Local `HH:MM` the work began. Absent lets the engine place it at local noon. */
+    readonly startClock: Schema.optional<Schema.String>;
+    readonly ticketKey: Schema.String;
+}>;
+/** Treat one ticket as yours whatever Jira says its assignee is. Sticks, in `~/.jcf/config.json`. */
+export declare const OwnershipPayload: Schema.Struct<{
+    readonly ticketKey: Schema.String;
+}>;
+export declare const OwnershipResult: Schema.Struct<{
+    readonly ownershipOverrides: Schema.$Array<Schema.String>;
+}>;
+/** Map a directory prefix to an Issue Key, so recurring ticket-less work stops being unplaced. */
+export declare const StandingPayload: Schema.Struct<{
+    readonly cwd: Schema.String;
+    readonly ticketKey: Schema.String;
+}>;
+export declare const StandingResult: Schema.Struct<{
+    readonly sessionTicketMap: Schema.$Record<Schema.String, Schema.String>;
+}>;
+export type WeekPlanResponse = Schema.Schema.Type<typeof WeekPlan>;
+export type WeekRowResponse = Schema.Schema.Type<typeof WeekRow>;
+export type RowProposalResponse = Schema.Schema.Type<typeof RowProposal>;
+export type UnattributedDayResponse = Schema.Schema.Type<typeof UnattributedDay>;
+export type WriteResultResponse = Schema.Schema.Type<typeof WriteResult>;
+export type WeekScopeName = Schema.Schema.Type<typeof WeekScope>;
+export type WriteTargetsRequest = Schema.Schema.Type<typeof WriteTargets>;
+export type RecordedIntervalResponse = Schema.Schema.Type<typeof RecordedInterval>;
+export type ProposalBlockResponse = Schema.Schema.Type<typeof ProposalBlock>;
+export type NotMineRowResponse = Schema.Schema.Type<typeof NotMineRow>;
+export type OwnershipMode = "assigned" | "any";
+/** Actual server stages. Counts describe completed attribution work, never estimated percentages. */
+export declare const ReadProgress: Schema.Struct<{
+    readonly activity: Schema.optional<Schema.Struct<{
+        readonly batch: Schema.Number;
+        readonly batches: Schema.Number;
+        readonly kind: Schema.Literals<readonly ["status", "text", "request", "response"]>;
+        readonly text: Schema.String;
+    }>>;
+    readonly stage: Schema.Literals<readonly ["sessions", "attribution", "recorded", "issues", "calendar"]>;
+    readonly message: Schema.String;
+    readonly completed: Schema.optional<Schema.Number>;
+    readonly total: Schema.optional<Schema.Number>;
+}>;
+export type ReadProgress = typeof ReadProgress.Type;
+/** One authenticated read stream, ending in exactly one plan or failure. */
+export declare const WeekReadEvent: Schema.Union<readonly [Schema.TaggedStruct<"Progress", {
+    readonly progress: Schema.Struct<{
+        readonly activity: Schema.optional<Schema.Struct<{
+            readonly batch: Schema.Number;
+            readonly batches: Schema.Number;
+            readonly kind: Schema.Literals<readonly ["status", "text", "request", "response"]>;
+            readonly text: Schema.String;
+        }>>;
+        readonly stage: Schema.Literals<readonly ["sessions", "attribution", "recorded", "issues", "calendar"]>;
+        readonly message: Schema.String;
+        readonly completed: Schema.optional<Schema.Number>;
+        readonly total: Schema.optional<Schema.Number>;
+    }>;
+}>, Schema.TaggedStruct<"Complete", {
+    readonly plan: Schema.Struct<{
+        /**
+         * True when a Coding Agent was needed and could not be reached. The deterministic rows are still
+         * complete; what is missing is only the placement of sessions no branch or path could place.
+         */
+        readonly attributorAvailable: Schema.Boolean;
+        readonly attributorCalls: Schema.Number;
+        readonly days: Schema.$Array<Schema.String>;
+        readonly excludedDays: Schema.$Array<Schema.Struct<{
+            readonly day: Schema.String;
+            readonly reason: Schema.String;
+        }>>;
+        readonly monday: Schema.String;
+        /** Names the server-held evidence a confirmation refers to. */
+        readonly planId: Schema.String;
+        readonly rows: Schema.$Array<Schema.Struct<{
+            readonly clockifyDescription: Schema.NullOr<Schema.String>;
+            readonly clockifySeconds: Schema.Number;
+            readonly day: Schema.String;
+            /**
+             * When the recorded time happened — the entries behind the totals, so a week can be drawn as a
+             * calendar. Empty when the systems reported no usable interval, never fabricated from the total.
+             */
+            readonly intervals: Schema.$Array<Schema.Struct<{
+                readonly entry: Schema.optionalKey<Schema.Struct<{
+                    /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+                    readonly revision: Schema.String;
+                    readonly id: Schema.String;
+                    readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+                    readonly ticketKey: Schema.NullOr<Schema.String>;
+                    readonly startMs: Schema.Number;
+                    readonly endMs: Schema.Number;
+                    readonly description: Schema.NullOr<Schema.String>;
+                }>>;
+                readonly endMs: Schema.Number;
+                readonly source: Schema.Literals<readonly ["clockify", "jira"]>;
+                readonly startMs: Schema.Number;
+            }>>;
+            readonly jiraSeconds: Schema.Number;
+            readonly proposal: Schema.optional<Schema.Struct<{
+                readonly activeSeconds: Schema.Number;
+                /**
+                 * The stretches behind this row, ascending. They sum to `maxSeconds`, and a confirmation may name
+                 * a subset of them by position — which is how a morning gets written without the afternoon.
+                 */
+                readonly blocks: Schema.$Array<Schema.Struct<{
+                    /** Normalized seconds this source block already supplied to each provider, including corrected-ticket writes. */
+                    readonly consumed: Schema.Struct<{
+                        readonly clockify: Schema.Number;
+                        readonly jira: Schema.Number;
+                    }>;
+                    /** A provider-specific safety hold, never a consumed-seconds estimate. */
+                    readonly clockifyRefusal: Schema.optionalKey<Schema.Literal<"unlinked-overlap">>;
+                    readonly endMs: Schema.Number;
+                    readonly seconds: Schema.Number;
+                    readonly startMs: Schema.Number;
+                    /** Stable source-cluster identity; rendered starts may move as overlapping work grows. */
+                    readonly sourceStartMs: Schema.optional<Schema.Number>;
+                }>>;
+                readonly clockifyDelta: Schema.Number;
+                readonly confidence: Schema.NullOr<Schema.Number>;
+                readonly jiraDelta: Schema.Number;
+                readonly maxSeconds: Schema.Number;
+                readonly sessionCount: Schema.Number;
+                readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+            }>>;
+            readonly rowId: Schema.String;
+            readonly ticketKey: Schema.String;
+            /**
+             * The issue title, or null when Jira could not be asked — logged out, unreachable, or out of
+             * scope for this week. Null is "unknown", never "untitled": an Issue Key alone is a lookup nobody
+             * can do six months later, so it is worth saying when it is missing.
+             */
+            readonly ticketTitle: Schema.NullOr<Schema.String>;
+        }>>;
+        /** Closed Clockify entries without a ticket, excluded from ticket reconciliation. */
+        readonly unlinkedClockify: Schema.$Array<Schema.Struct<{
+            readonly entry: Schema.optionalKey<Schema.Struct<{
+                /** Opaque retained snapshot handle. Send unchanged when saving; use the returned handle afterward. */
+                readonly revision: Schema.String;
+                readonly id: Schema.String;
+                readonly source: Schema.Literals<readonly ["jira", "clockify"]>;
+                readonly ticketKey: Schema.NullOr<Schema.String>;
+                readonly startMs: Schema.Number;
+                readonly endMs: Schema.Number;
+                readonly description: Schema.NullOr<Schema.String>;
+            }>>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly description: Schema.NullOr<Schema.String>;
+            readonly startMs: Schema.Number;
+            readonly endMs: Schema.Number;
+        }>>;
+        readonly sessionCount: Schema.Number;
+        /** False for recorded-only weeks. Omitted by older servers means a session scan is available. */
+        readonly sessionScanAvailable: Schema.optional<Schema.Boolean>;
+        /** Which systems this week was read from. A side that is out reports zero because nobody asked. */
+        readonly scope: Schema.Literals<readonly ["both", "clockify", "jira"]>;
+        /** Zero means nothing is opted in, which is the usual reason for an empty week. */
+        readonly sessionRootCount: Schema.Number;
+        /** Hours on tickets assigned to somebody else. Empty when ownership is not being enforced. */
+        readonly notMine: Schema.$Array<Schema.Struct<{
+            /** Who Jira says owns it, or null when it is unassigned. */
+            readonly assignee: Schema.NullOr<Schema.String>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly signal: Schema.Literals<readonly ["branch", "path", "standing", "agent", "none"]>;
+            readonly ticketKey: Schema.String;
+            readonly ticketTitle: Schema.NullOr<Schema.String>;
+        }>>;
+        /**
+         * True when Jira actually answered about who owns these tickets.
+         *
+         * False means nothing was filtered on ownership, whatever the setting says — a week that quietly
+         * hid rows because Jira was unreachable would be a week missing hours with nothing to explain it.
+         */
+        readonly ownershipChecked: Schema.Boolean;
+        /** Whether this week withheld tickets assigned to other people. */
+        readonly ownership: Schema.Literals<readonly ["assigned", "any"]>;
+        readonly unattributed: Schema.$Array<Schema.Struct<{
+            readonly cwds: Schema.$Array<Schema.String>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly sessionCount: Schema.Number;
+        }>>;
+        readonly withheld: Schema.$Array<Schema.Struct<{
+            readonly confidence: Schema.NullOr<Schema.Number>;
+            readonly day: Schema.String;
+            readonly seconds: Schema.Number;
+            readonly ticketKey: Schema.String;
+            readonly ticketTitle: Schema.NullOr<Schema.String>;
+        }>>;
+    }>;
+}>, Schema.TaggedStruct<"Failed", {
+    readonly message: Schema.String;
+}>]>;
+export type WeekReadEvent = typeof WeekReadEvent.Type;
+export {};