time.loc

Canonical temporal-spatial primitive for governed systems. Apache 2.0.

time.loc is a 14-field, HMAC-integrity record that answers the fundamental audit question — when and where did this happen? — in a single, tamper-evident, version-stamped structure.

Every governed event that needs to be auditable, correlated across systems, or validated retroactively should embed a time.loc record. It is the temporal anchor; nothing is auditable without it.

What it is

Dual timestamps — local (with UTC offset) and UTC. Both are required.
Geolocation with provenance — not just where, but how the location was determined: declared, ip, gps, or unavailable. When unavailable, all geo fields are null by contract.
ULID sequence identifier — monotonic, globally unique, sortable by string comparison without parsing.
HMAC-SHA256 integrity — over all fields except itself in canonical pipe-delimited form. Unsigned records declare "unsigned" explicitly, not null.
GPS coordinate fields (v1.2) — geo.lat, geo.lon, geo.alt for GPS-equipped devices. Null everywhere else.

Spec

See spec/time-loc-v1.2.md for the full specification.

Governed by eco PASS 0050.02 (accepted 2026-04-04).

Python reference implementation

Install

pip install time-loc @ git+https://github.com/governancecommons/time-loc
# or, from a local checkout:
pip install -e /path/to/time-loc

Installs three flat top-level modules — time_loc, time_loc_compact, time_loc_validator — matching the import statements below. Pulls in python-ulid and base58 automatically.

Dependencies

pip install python-ulid base58

Produce a record

from time_loc import produce, produce_declared, produce_gps, produce_unsigned_unavailable

# Declared location (human-stated)
record = produce_declared(city="Longview", region="WA", country="US")
print(record.to_dict())

# GPS location
record = produce_gps(latitude=46.138, longitude=-122.938, altitude=12.5)
print(record.to_dict())

# Agent/cloud — no location, no signing key
record = produce_unsigned_unavailable()
print(record.to_dict())

Validate a record

from time_loc_validator import validate_time_loc_v1_2

record_dict = { ... }
errors = validate_time_loc_v1_2(record_dict)
if errors:
    print("invalid:", errors)
else:
    print("valid")

Compact encoding

from time_loc_compact import encode_compact, decode_compact

# Encode a time.loc record dict to a compact base58 string
compact = encode_compact(record.to_dict())

# Decode back to fields 0-9 dict
fields = decode_compact(compact)

Files

File	Description
`spec/time-loc-v1.2.md`	Full specification
`python/time_loc.py`	Producer — frozen dataclass + `produce()` factory
`python/time_loc_compact.py`	Compact (base58) encoder/decoder
`python/time_loc_validator.py`	Validator — returns list of violation strings
`python/time_loc_schema.json`	JSON Schema draft-07
`python/time_loc_examples.json`	Canonical examples (declared, gps, unavailable)

Used by

governancecommons/governed-event — the Governed Event Envelope embeds a time.loc record in every governed event.

License

Apache 2.0 — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

time_loc-1.2.0.tar.gz (9.9 kB view details)

Uploaded Aug 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

time_loc-1.2.0-py3-none-any.whl (11.1 kB view details)

Uploaded Aug 23, 2026 Python 3

File details

Details for the file time_loc-1.2.0.tar.gz.

File metadata

Download URL: time_loc-1.2.0.tar.gz
Upload date: Aug 23, 2026
Size: 9.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for time_loc-1.2.0.tar.gz
Algorithm	Hash digest
SHA256	`89a16af82b30eca3f17c97cca2894442ece4bce8bc06e97965ded69c6dc2bb17`
MD5	`654b4969a6beb6fc116554311cd2935b`
BLAKE2b-256	`7c8005bee7f05f594d5eff29c9bc64a735dfa1908a09b706a0a8ac338779e61d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for time_loc-1.2.0.tar.gz:

Publisher: publish.yml on governancecommons/time-loc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: time_loc-1.2.0.tar.gz
- Subject digest: 89a16af82b30eca3f17c97cca2894442ece4bce8bc06e97965ded69c6dc2bb17
- Sigstore transparency entry: 2568867908
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: governancecommons/time-loc@35c6ac781a390614dfe07f72750442d57161fdfd
- Branch / Tag: refs/heads/main
- Owner: https://github.com/governancecommons
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@35c6ac781a390614dfe07f72750442d57161fdfd
- Trigger Event: workflow_dispatch

File details

Details for the file time_loc-1.2.0-py3-none-any.whl.

File metadata

Download URL: time_loc-1.2.0-py3-none-any.whl
Upload date: Aug 23, 2026
Size: 11.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for time_loc-1.2.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`198deb0dd268e2a2e119b24af78d59046d5dd18028aa2e05085dc4852902fabf`
MD5	`34714b138ce86f234b1a161417c419c7`
BLAKE2b-256	`9e1616dd069b6f9aa5c7e1bfb69ce35b511c3cf235c6ec39f9c8ba7f859d777a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for time_loc-1.2.0-py3-none-any.whl:

Publisher: publish.yml on governancecommons/time-loc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: time_loc-1.2.0-py3-none-any.whl
- Subject digest: 198deb0dd268e2a2e119b24af78d59046d5dd18028aa2e05085dc4852902fabf
- Sigstore transparency entry: 2568867912
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: governancecommons/time-loc@35c6ac781a390614dfe07f72750442d57161fdfd
- Branch / Tag: refs/heads/main
- Owner: https://github.com/governancecommons
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@35c6ac781a390614dfe07f72750442d57161fdfd
- Trigger Event: workflow_dispatch

Release history Release notifications | RSS feed

This release

1.2.0 This release

Aug 23, 2026 2 files

time-loc 1.2.0

time.loc

What it is

Spec

Python reference implementation

Install

Dependencies

Produce a record

Validate a record

Compact encoding

Files

Used by

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Provides Extra

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed